Update READMEs and CHANGELOG for v1.0.0

2020-07-09 17:34:37 +02:00 · 2020-07-09 17:34:37 +02:00 · c7bbac61b6
parent c2285ceec2
commit c7bbac61b6
5 changed files with 109 additions and 43 deletions
--- a/27
+++ b/27
@ -1,4 +1,29 @@
-master 2019-02-24
+v1.0.0 2020-07-09
+
+* Rename Callbacks to FederatingCallbacks in FederatingProtocol.
+* Rename Callbacks to SocialCallbacks in SocialProtocol.
+* Rename NewID to NewID on the Database interface.
+* Added approx. 200 unit tests at ~70% LOC coverage.
+* More fixes where nil pointers would be dereferenced.
+* Modified programmatic delivery to be lenient instead of strict.
+* Even more 'astool' bugfixes to handle multiple vocabulary code generation.
+* Added request lifecycle hooks to allow implementations greater control when
+      using the 'context' standard library package and its 'Context'.
+* Fixed bugs in programmatic delivery, handling rare forms of HTTP successes,
+      handling of JSON-LD's @context, race conditions.
+* Provide a Mastodon-compliant http-signatures Transport implementation, when
+      using the github.com/go-fed/httpsig library.
+* Support programmatic sending of Activities
+* Added support for 3 vocabularies in addition to ActivityStreams: toot
+      (Mastodon), security v1, and ForgeFed.
+* Modify 'astool' to address quirky logic and underspecification in various
+      vocabulary definitions.
+* Fixed bugs in the 'astool' logic.
+* Added more helpful functions to the code generated by 'astool'.
+* Inbox forwarding bug fixes.
+* Migrate to go modules.
+
+2019-02-24

 * Removed 'tools'.
 * Removed 'vocab'.
--- a/README.md
+++ b/README.md
@ -10,35 +10,51 @@ ActivityStreams vocabulary.
 * `pub`: ActivityPub Social Protocol (Client-to-Server or C2S) and Federating
 Protocol (Server-to-Server or S2S)

+Check out [go-fed.org](https://go-fed.org/) for tutorials and documentation.
+
 ## Status

-**Preview (unstable) 1.0.0** ([Semantic Versioning](https://semver.org/))
+**1.0.0** ([Semantic Versioning](https://semver.org/))
+
+This library has been successfully used to
+[federate since May 17, 2019](https://cjslep.com/c/blog/this-blog-is-federated).

 An [official implementation report](https://activitypub.rocks/implementation-report/)
 was last submitted for version **0.2.0** [here](https://github.com/w3c/activitypub/issues/318).
-
+Unfortunately, the official implementation report tool is no longer maintained.
 Previous unofficial implementation reports are available in [issue #46](https://github.com/go-fed/activity/issues/46).

 Please see CHANGELOG for changes between versions.

 ## Getting Started

-See `astool`, `streams`, or `pub` for their own README.
+Check out [go-fed.org](https://go-fed.org/) for tutorials and documentation.

-## How can I get help, file issues, or contribute?
+Also, see `astool`, `streams`, or `pub` for their own README.

-Please see the CONTRIBUTING.md file!
+## FAQ

-## How well tested are these libraries?
+### What vocabularies are supported?
+
+* [ActivityStreams](https://www.w3.org/TR/activitystreams-vocabulary).
+* A subset of the [toot](https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/adapter.rb) vocabulary.
+* A subset of the [security](https://w3c-ccg.github.io/security-vocab/) vocabulary.
+* [ForgeFed](https://forgefed.peers.community/vocabulary.html).
+
+### How well tested are these libraries?

 I took great care to add numerous tests using examples directly from
 specifications, official test repositories, and my own end-to-end tests.

-**v1.0.0** still has a lot of unit tests to be written. Bug fixes and small
-backwards-incompatible behavior is expected before it is blessed as being
-released.
+**v1.0.0** has around 200 unit tests. The **federation** or **S2S** portion of
+the library is very well tested. The **social** or **C2S** portion could use
+additional unit tests, but is far less popular than federation. About 70% of the
+lines are covered by unit tests.

-## Who is using this library currently?
+### Who is using this library currently?
+
+Note: This list only includes those who have reached out to me to explicitly be
+included.

 | Application | Description                                       | Repository                                                                 | Point Of Contact                                                                                                    | Homepage                             |
 |:-----------:|:-------------------------------------------------:|:--------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------:|:------------------------------------:|
@ -47,15 +63,17 @@ released.
 | Read.as       | Long-form reader built on open protocols                       | [https://github.com/writeas/Read.as](https://github.com/writeas/Read.as)         | [@write_as@writing.exchange](https://writing.exchange/@write_as) or [hello@write.as](mailto:hello@write.as)         | [https://read.as](https://read.as)                 |
 | go-fed/apcore | Generic ActivityPub server framework in Go                     | [https://github.com/go-fed/apcore](https://github.com/go-fed/apcore)             | [@cj@mastodon.technology](https://mastodon.technology/@cj) or [cjslep@gmail.com](mailto:cjslep@gmail.com)           | [https://go-fed.org](https://go-fed.org)           |

-## How do I use these libraries?
+### How do I use these libraries?
+
+Check out [go-fed.org](https://go-fed.org/) for tutorials and documentation.

 Please see each subdirectory for its own README for further elaboration.

-## FAQ
+### How can I get help, file issues, or contribute?

 Please see the CONTRIBUTING.md file!

-## Useful References
+### Useful References

 * [ActivityPub Specification](https://www.w3.org/TR/activitypub)
 * [ActivityPub GitHub Repo](https://github.com/w3c/activitypub)
--- a/astool/README.md
+++ b/astool/README.md
@ -52,9 +52,8 @@ tool is `activitystreams.jsonld` which contains the OWL2 definition of the
 ActivityStreams specification. To generate the code, in your `$GOPATH` do:

 ```
-mkdir tmp
-cd tmp
-astool -spec activitystreams.jsonld
+cd $GOPATH/github.com/go-fed/activity/astool
+go generate
 ```

 This will automatically generate a number of files containing the functions,
--- a/pub/README.md
+++ b/pub/README.md
@ -2,10 +2,10 @@

 Implements the Social and Federating Protocols in the ActivityPub specification.

-## Preview Release
+## Reference & Tutorial

-v1.0.0 still has a lot of unit tests that need to be written. Please run
-`go test -v` to see the latest state of unit testing.
+The [go-fed website](https://go-fed.org/) contains tutorials and reference
+materials, in addition to the rest of this README.

 ## How To Use

@ -13,35 +13,57 @@ v1.0.0 still has a lot of unit tests that need to be written. Please run
 go get github.com/go-fed/activity
 ```

-The root of all ActivityPub behavior is the `Actor`:
+The root of all ActivityPub behavior is the `Actor`, which requires you to
+implement a few interfaces:

 ```golang
-// Only support Social protocol
+import (
+  "github.com/go-fed/activity/pub"
+)
+
+type myActivityPubApp struct { /* ... */ }
+type myAppsDatabase struct { /* ... */ }
+type myAppsClock struct { /* ... */ }
+
+var (
+  // Your app will implement pub.CommonBehavior, and either
+  // pub.SocialProtocol, pub.FederatingProtocol, or both.
+  myApp = &myActivityPubApp{}
+  myCommonBehavior pub.CommonBehavior = myApp
+  mySocialProtocol pub.SocialProtocol = myApp
+  myFederatingProtocol pub.FederatingProtocol = myApp
+  // Your app's database implementation.
+  myDatabase pub.Database = &myAppsDatabase{}
+  // Your app's clock.
+  myClock pub.Clock = &myAppsClock{}
+)
+
+// Only support the C2S Social protocol
 actor := pub.NewSocialActor(
-  myAppsCommonBehavior,
-  myAppsSocialProtocol,
-  myAppsDatabase,
-  myAppsClock)
+  myCommonBehavior,
+  mySocialProtocol,
+  myDatabase,
+  myClock)
 // OR
 //
-// Only support Federating protocol
+// Only support S2S Federating protocol
 actor = pub.NewFederatingActor(
-  myAppsCommonBehavior,
-  myAppsFederatingProtocol,
-  myAppsDatabase,
-  myAppsClock)
+  myCommonBehavior,
+  myFederatingProtocol,
+  myDatabase,
+  myClock)
 // OR
 //
-// Support both Social and Federating protocol.
+// Support both C2S Social and S2S Federating protocol.
 actor = pub.NewActor(
-  myAppsCommonBehavior,
-  myAppsSocialProtocol,
-  myAppsFederatingProtocol,
-  myAppsDatabase,
-  myAppsClock)
+  myCommonBehavior,
+  mySocialProtocol,
+  myFederatingProtocol,
+  myDatabase,
+  myClock)
 ```

-Next, hook the `Actor` into the HTTP server:
+Next, hook the `Actor` into your web server:

 ```golang
 // The application's actor
@ -93,10 +115,7 @@ server.Handler = serveMux
 To serve ActivityStreams data:

 ```golang
-myHander := pub.NewActivityStreamsHandler(
-  myAppsAuthenticateFunc,
-  myAppsDatabase,
-  myAppsClock)
+myHander := pub.NewActivityStreamsHandler(myDatabase, myClock)
 var activityStreamsHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
  c := context.Background()
  // Populate c with request-specific information
@ -239,7 +258,7 @@ interface can be used to obtain an `Actor`:
 ```golang
 // Use custom ActivityPub implementation
 actor = pub.NewCustomActor(
-  myAppsDelegateActor,
+  myDelegateActor,
  isSocialProtocolEnabled,
  isFederatedProtocolEnabled,
  myAppsClock)
--- a/streams/README.md
+++ b/streams/README.md
@ -2,6 +2,11 @@

 ActivityStreams vocabularies automatically code-generated with `astool`.

+## Reference & Tutorial
+
+The [go-fed website](https://go-fed.org/) contains tutorials and reference
+materials, in addition to the rest of this README.
+
 ## How To Use

 ```