commit a510c142ef4a06df8f8af87a87b13a26d2e78b01
parent e3efd43f94e6f502942e52c0a77474c1ab474962
Author: Oliver Lowe <o@olowe.co>
Date: Sat, 20 Jul 2024 17:04:42 +1000
misc: add code review section
Having some specific guides to point to I think makes it easier for
others to contribute. It saves time if someone reads it before,
and it helps to stave off that "taking it personally" thing (which
I certainly get sometimes!) if they read it after submitting a
change too.
Diffstat:
| M | README.md | | | 39 | +++++++++++++++++++++++++++++++++------ |
1 file changed, 33 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@ We use these packages to self-host the livestream at [olowe.co/live].
Larger, fleshed-out tasks are managed in
[issues](https://github.com/untangledco/streaming/issues).
-We can put `TODO` notes in the source code, too.
+There are `TODO` notes in the source code, too.
[godoc] provides a graphic interface to view these
with the `-notes` flag:
@@ -35,14 +35,13 @@ Of course `grep` works too:
Patches are preferred via email so that we're not too locked in to GitHub.
Post them to the mailing list
-[~otl/untangledco@lists.sr.ht](mailto:~otl/untangledco@lists.sr.ht),
-([archives](https://lists.sr.ht/~otl/untangledco))
-or to [Oliver Lowe](mailto:o@olowe.co).
-See [git-send-email.io](https://git-send-email.io) if you're unfamiliar with the workflow.
+[~otl/untangledco@lists.sr.ht] ([archives]).
+or to [Oliver Lowe].
+See [git-send-email.io] if you're unfamiliar with the workflow.
git config sendemail.to '~otl/untangledco@lists.sr.ht'
-We also accept changes via [pull request](https://github.com/untangledco/streaming/pulls).
+We also accept changes via [pull request].
### Commit messages
@@ -56,7 +55,35 @@ For example:
This matches what the spec allows, and lets users not worry about
encoding.
+[archives]: https://lists.sr.ht/~otl/untangledco
+[~otl/untangledco@lists.sr.ht]: mailto:~otl/untangledco@lists.sr.ht
+[git-send-email.io]: https://git-send-email.io
+[pull request]: https://github.com/untangledco/streaming/pulls
+
+### Code review
+
+We try to make all code feel familiar to Go programmers
+so that it's easier for others to learn from and contribute to in the
+future.
+
+In general we follow the guidelines laid out in the following articles:
+
+- [Effective Go]
+- [Go Code Review Comments]
+
+Don't worry if you're asked about changing things around!
+If there are trivial changes, we may make the changes ourselves.
+In this case you still retain all authorship and copyright over your
+submission.
+
+If you've read this far and want to join in but feel a little unsure;
+I know *exactly* how you feel.
+Please feel free to email [Oliver Lowe] and maybe I can help out :)
+
+[Effective Go]: https://go.dev/doc/effective_go
+[Go Code Review Comments]: https://go.dev/wiki/CodeReviewComments
[Go]: https://go.dev/doc/contribute#commit_messages
+[Oliver Lowe]: mailto:o@olowe.co
## License
