PushFish - Repository Documentation Standards
This document outlines the standards for all public, open-source repositories used by PushFish.
The goal of this document is to ensure that PushFish documentation is welcoming, informative, comprehensive, and well-written.
Each codebase should include the following documents, committed as markdown files at the top level of the repository.
This document exists to introduce a project to a new visitor. It may also serve as a reference document for existing contributors. This document should include the following:
Title / Heading
- The title (name) of the project at the top as an h1
- Any build status badges as appropriate immediately below the title
- A one or two sentence description of the project, below the title or status badges. The description should mention the language, and any key frameworks (e.g. “PushFish” should mention it uses both Python and golang).
- A screenshot, image or gif of the project below the description (host it on spee.ch!)
- A table of contents if the document is long (can be one line of links to sections).
- A single header labeled “Install” should be the next header as an h2
- Installation means installation for users. It should cover how to have the software on their computer in a user-friendly fashion, not how to run from source. E.g. it should link binaries if they exist.
- If the project is a library only intended to be used in other projects, it should still exist but can be extremely succinct (e.g. pip install pushfish-api)
- If the project is not designed to be installed directly or used as a library in other projects, it should state as such, e.g. “This project is not designed to be installed directly. Continue reading below to learn how to use this project.”
- A single header labeled “Usage” should be the next header as an h2
- The Usage section should explain how to run or launch the project if applicable.
- The Usage section should include examples of some basic commands, if applicable.
- In the case of a library, it should provide a few basic examples of how the library would be used.
- Usage should always be included, even if very simple. For example,
“Run the following
httpiecommands to begin interacting with the API.”
Running from Source
- This section covers how to run the project from source and/or with the intent of working directly on it.
- It can have a Prerequisites section for what is required to run from source.
- It is okay to assume some basic assumptions about what people know about the language or tools the project uses. However, it’s good when possible to assume very little, and provide links to the user for how to get the prerequisites.
- For prerequisites that it is not safe to assume knowledge of, the project should list the explicit command to add the prerequisite, or link to instructions on how to add the prerequisite.
- If there are operating system specific instructions, these should be broken out into separate headings for each operating system.
- It is okay to assume Linux and Unix are “first class citizens”. While we want to support all OSes, Windows instructions and considerations can be secondary.
- Include a step that explains how to verify you are running from source directly.
- It is okay to point to a INSTALL.md file if the installation steps are relatively lengthy, which should reside in the root folder.
- A single header labeled “Contributing” should appear as an h2
- This should be the same copy: “Contributions to this project are welcome, encouraged, and compensated. For more details, see CONTRIBUTING.md”
- If CONTRIBUTING.md does not exist in the project, it should link to https://push.fish/contributing
- Additional headings as appropriate will typically exist after the above and below the subsequent areas.
- These areas should cover anything else appropriate or helpful to introduce a project to a new user.
- A single header labeled “License” should appear as an h2
- Assuming a standard license, this should be the same two sentences: “This project is X licensed. For the full license, see [LICENSE].”
- “We take security seriously. Please contact [email protected] regarding any security issues.
- A single header labeled “Contact” should appear as an h2
- This should be the same or similar copy: “The primary contact for this project is @XXX ([email protected])”
Additional Info and Links
- References to any additional documentation, such as generated API docs.
This document explains anything a visitor would need to know to contribute to the project.
This document should cover the following:
- First, it should contain a single sentence: “This project follows the global contributing standards for all PushFish projects, to read those go < here >”.
- A “Code Overview” section explaining some basic design choices and how to begin stepping through the code. An example would be explaining that application.py is the primary entry point for the API server code, and how the various PushFish components work together.
- A “Testing” section, explaining how to run tests, and that tests are necessary.
- Information on how to submit pull requests, and what to expect afterwards. (e.g. a link to our branching doc, commands to run before submitting PR, tests must pass, changelog entry, etc). If you find this gets repetitive, it may be best to link to a global doc.
- Anything else a new visitor to a repository should know about contributing to that specific repository (linting, generating documentation, etc).
Every repository should have a LICENSE file stating the license. The default license we use is BSD, and we license all code as BSD whenever possible.
Some code may use external libraries that prevent BSD licensing. If adding a license to a project for the first time that uses 3rd-party code, please ensure it is okay to actually BSD license it.
A template for issues should exist to guide users in correctly filing them.
Style and Formatting Notes
- Rely on autowrap instead of manually breaking up paragraphs with carriage return.