From b3fadf08f4c0ca1af3641e5b63fd33a023bfc071 Mon Sep 17 00:00:00 2001
From: Alberto Bertogli <albertito@blitiri.com.ar>
Date: Sat, 25 Jan 2025 12:39:29 +0000
Subject: [PATCH] docs: Add guidelines for contributing

This patch adds a document with guidelines for contributing to chasquid.

It includes suggestions for how to ask questions, how to send patches
(and the expectations around them), and documents how the different
branches are used.

Thanks to raspbeguy (https://github.com/raspbeguy) for suggesting this
improvement.
---
 .mkdocs.yml          |  9 +++++++
 docs/contributing.md | 60 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)
 create mode 100644 docs/contributing.md

diff --git a/.mkdocs.yml b/.mkdocs.yml
index a5700ca..792fe37 100644
--- a/.mkdocs.yml
+++ b/.mkdocs.yml
@@ -16,6 +16,10 @@ markdown_extensions:
 
 theme: readthedocs
 
+exclude_docs: |
+  man/*.1
+  man/*.5
+
 nav:
 - Home: index.md
 - How-to: howto.md
@@ -35,4 +39,9 @@ nav:
     - tests.md
     - relnotes.md
     - knownissues.md
+    - contributing.md
+
+not_in_nav: |
+  security.md
+  man/*
 
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..ff3f2ed
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,60 @@
+
+# Contributing
+
+## Questions and bug reports
+
+Please send questions and bug reports via [Github Issues], or to the [mailing
+list], chasquid@googlegroups.com.  
+To subscribe to the [mailing list], send an email to
+`chasquid+subscribe@googlegroups.com`.
+
+To privately report a suspected security issue, please see [Reporting a
+security issue](security.md).
+
+<a name="irc"></a>
+You can also reach out via IRC, `#chasquid` on [OFTC](https://oftc.net/).
+
+
+## Patches and pull requests
+
+You can send patches and pull requests via [Github Pull requests], or the
+[mailing list].
+
+Before sending any non-trivial change, it's ideal to discuss the proposal (via
+[Github Issues], [mailing list], or [IRC](#irc)). This helps make the most out
+of the contribution, and minimize friction frustration during code reviews.
+
+
+### Commit message, coding style, tests
+
+Ideally, patches would have descriptive commit messages, adhere to Go's coding
+style, and include comprehensive tests.  However, that is a lot to ask, and
+very subjective.
+
+It is okay to propose patches without those things. In those cases, the
+maintainer will usually amend the patches to add them.
+
+For how to write commit messages,
+[this](https://chris.beams.io/posts/git-commit/) and
+[this](https://git-scm.com/docs/SubmittingPatches#describe-changes) articles
+contain great advise.
+
+
+### Workflow
+
+Patches will be cherry-picked, and are typically first incorporated into the
+`next` branch.
+
+The `next` branch is where patches are staged, tested and reviewed. This
+branch is rebased frequently, to make adjustments and fixes as needed.
+Once patches have received enough testing (usually after a couple of weeks),
+they are moved to the `main` branch.
+
+The `main` branch is the stable branch and where releases are cut from. It is
+never rebased.
+
+
+[Github Issues]: https://github.com/albertito/chasquid/issues
+[mailing list]: https://groups.google.com/forum/#!forum/chasquid
+[GitHub's Security tab]: https://github.com/albertito/chasquid/security
+[Github Pull requests]: https://github.com/albertito/chasquid/pulls