Write Documentation

Thorough and update-to-date documentation is an integral part of the Furem Cape project. We welcome and appreciate all documentation contributions!

Overview

The documentation source files for Furem Cape are written in reStructuredText markup, and kept in the same Git repository as the Furem Cape source code, in the docs sub-directory of the root repository directory. The official Furem Cape Git repository is https://git.sr.ht/~arx10/furemcape. Documentation is kept in sync and released along with the code, and the process for adding and updating documentation is basically the same as adding and updating code.

For patches that include both source code and documentation, please follow the development process outlined on the Code page. For documentation-only patches, you can follow this documentation-specific process:

Documentation Process

Prerequisites

To access the documentation source files, you need to have a Git client installed on your local computer.

To preview your changes locally, you’ll need to either a) have Docker installed on your local computer, or b) create a Python virtual environment (using Python 3.6 or newer) and install the requirements listed in the requirements/doc.txt file (from the root of the Furem Cape project) into the virtual environment with Pip.

Edit Source Files

Use your Git client to clone the Furem Cape Git repository at https://git.sr.ht/~arx10/furemcape. Open up the .rst files from the docs/source directory tree in a text editor, and edit them (or add more .rst files) as necessary. The .rst extension stands for reStructuredText, so you may want to use a text editor that has built-in support for reStructuredText (or with a plugin that supports reStructuredText) – but any editor that can edit plain text files will work.

Preview With Docker

To preview your changes with Docker, run the following command from the root of the Furem Cape project:

make watch.docs

This will automatically start up a Docker container for building the docs, build the docs as HTML files to the docs/build/html directory, and serve them on port 8778 on your local host. Open up a web browser, and enter the following into the location bar:

http://localhost:8778/

This will show your working copy of the documentation site. While the Docker container is running, every time you save a change to the documentation source files, the container will automatically re-build the docs as HTML, and (after a moment, once they’re re-built) refresh them in your browser.

Make a Git Commit

Once you have made changes to your liking, create a new private branch in Git for your changes, and commit them to that branch. With the command-line Git client, you’d execute the following commands (where my-first-changes would be the name of the branch – you can name it whatever you want):

git checkout -b my-first-changes
git add -A .
git commit

When prompted for a commit message, please follow the seven rules from How to Write a Git Commit Message:

  1. Separate subject from body with a blank line

  2. Limit the subject line to 50 characters

  3. Capitalize the subject line [optional for Furem Cape, but recommended]

  4. Do not end the subject line with a period

  5. Use the imperative mood in the subject line

  6. Wrap the body at 72 characters

  7. Use the body to explain what and why (not how)

Commit messages should also include a Signed-off-by line at the end of the body (see the Sign Off section).

Review Your Commit

The difference between the commit you just made and the previous commits in the repository is what you submit as a patch. There are a number of tools that allow you to view Git commits; a very simple way to view the last commit is to use the command-line Git client to run the following command:

git log -1 -p

This will display the commit message and “diff” (the difference between the current commit and the previous one) – and this is exactly the content that you submit when you submit a patch.

Sign Off

All patches submitted to the Furem Cape project must include a Signed-off-by line to certify that you are submitting it in accordance with the terms of the Developer Certificate of Origin (DCO). This certifies that you are either the author of the submitted content, or have the right to submit it under the open source license used by Furem Cape (the MIT License).

The Signed-off-by line must include your real name (the name with which you sign legal documents), and the email address you used to submit the patch, like so:

Signed-off-by: Alice X Writer <alice@example.com>

You can add a Signed-off-by line automatically to commit messages by including the --signoff option with the git commit command; or you can just add your Signed-off-by line manually to the bottom of each commit message.

If you forget to sign-off on a patch, you can just reply to the patch email thread with a message like “I certify the preceding patches in this thread were contributed in accordance with the DCO”, followed by your Signed-off-by line (or if you submitted the patch by tracker, add a comment like “I certify the preceding patches in this ticket were contributed in accordance with the DCO”, followed by your Signed-off-by line). Alternately (or if there might be some confusion as to which content you’re referring), you can just resubmit the full patch with your Signed-off-by line included.

Submit via Email

Send patches to our development list at ~arx10/furemcape-dev@lists.sr.ht. You don’t need to introduce yourself or subscribe, just send the patch – all contributions are appreciated!

The easiest way to send a patch is with the git send-email command. The Git Send-Email site provides a nice tutorial for how to configure Git and use the git send-email command. You can also send patches manually to the list with an email client that supports plain-text content.

Or Submit via Tracker

If submitting a patch via email seems too daunting or unfamiliar, you can instead create a ticket for the patch in our issue tracker at https://todo.sr.ht/~arx10/furemcape. Generate the patches to submit with the git format-patch command; for example, the following would export the last commit from your working branch to the my-furemcape-patch.txt file in your home folder:

git format-patch -1 --stdout > ~/my-furemcape-patch.txt

Open up that file in a text editor, and copy and paste its contents into the ticket’s description. See the Git Format-Patch manual page for more options with the git format-patch command.

Alternately (or if the patch is really big), if you’ve pushed a branch with the patch to a publicly-accessible repository (like on GitHub, GitLab, sourcehut, etc), you can just include a link to that repository and branch information in the ticket instead of the full patch content. The git request-pull command produces nicely formatted output for this purpose (but doesn’t do anything special that you can’t just as easily enter into the ticket manually).