Maintenance
Philosophy
The development of Scout involved, as much as possible, the implementation of what were identified as “best practices,” from the programming languages used to the formatting of the code. The language below outlines these practices.
Contributions
Version Control with Git and GitHub
Scout relies on git for version control.
Before Each Commit
Making a commit in git should not be a source of heartburn, but there are several steps that should be taken to ensure each commit is high quality.
Check all modified files for spelling errors (especially in the comment text)
Check all modified files against appropriate linters (e.g., PEP 8 and PEP 257 for Python) or to make sure the file is syntactically valid (e.g., for JSON files)
Check that the commit message itself is free of typos and spelling errors.
Check to make sure that all tests are passing
Documentation
The documentation for Scout is prepared using Sphinx, a package originally developed to document Python. Sphinx builds upon the reStructuredText markup language by adding a lot of handy features, like support for LaTeX equation markup with MathJax, automatic figure numbering, and simplified references to Python documentation. reStructuredText is a “semantic” markup language, and as a result, the documentation files have to be built to obtain their final, desired form.
Before contributing to or updating the documentation, try to think of documentation that you’ve encountered in the past that has been particularly helpful. Consider what made that documentation so useful to you - clarity of writing, extent of examples, explanations of edge cases, or overall structure. If nothing comes to mind, visit the Beautiful Docs page for a list of examples of high-quality documentation.