This section describes development standards and best practices within the project.
The PEP 8 is our baseline for coding style.
In short we use:
- 4 spaces per indentation
- 79 characters per line
- One import per line, grouped in the following order: standard library, 3rd party imports, local application imports
- One statement per line
- Docstrings for all public modules, functions, classes and methods.
The following naming conventions should be followed:
- Class names use CapitalWords
- Function names are lowercase, with words separated by underscores
clsfor first argument to instance and class methods, respectively.
- Non-public methods and variables should be prefixed with an underscore
- Constants in all uppercase.
Code should attempt to be idiomatic/pythonic, for example:
- Use list, dict and set comprehensions.
- Test existence in a sequence with
enumerateinstead of loop counters.
with ... as ...for context managers.
isto compare against
- Use parenthesis instead of backslashes for line continuations.
You can use
prospector to check your code style:
pip install -r requirements/local.txt prospector
We use Git as our Version Control System.
We have 2 long-term public branches:
master- The latest stable release. This branch should be tagged with a new version number every time a branch is merged into it.
develop- The release currently in development. New features and releases originate from this branch.
There are also multiple short-term supporting branches:
hotfix- Used for immediate changes that need to be pushed out into production. These branches should originate from
masterand be merged into
masterand either the
releaseif one exists.
feature- Used for individual features and bug fixes, these branches are usually kept on local development machines. These should originate from and be merged back into
release- Used for preparing the
developbranch for merging into
master, creating a new release. These branches should originate from
developand be merged back into
master. Releases should be created when all new features for a version are finished. Any new commits should only contain code refactoring and bug fixes.
This model is adapted from A Successful Git Branching Model, however we use
a linear history instead of a branching history, so the
should be omitted during merges.
Commit messages should follow the format described in A Note About Git Commit Messages. They should generally follow the following format:
[TaskID#] Short 50 Char or Less Title Explanatory text or summary describing the feature or bugfix, capped at 72 characters per line, written in the imperative. Bullet points are also allowed: * Add method `foo` to `Bar` class * Modify `Base` class to be abstract * Remove `foobaz` method from `Bar` class * Refactor `bazfoo` function Refs/Closes/Fixes #TaskID: Task Name in Bug Tracker
[#367] Customize General Layout & Home Page * Add the core app and a SeleniumTestCase class to the core.utils module to automatically start a live server and create a remote selenium driver. * Add the functional_tests.general_page_tests module to test elements that should be on every page. * Add the functional_tests.home_page_tests module to test elements that should appear on the home page. * Add basic site customizations, like modifying the title, tagline and homepage content. * Add requirements files for test and local environments. * Modify manage.py to use the thefec module's settings files * Move the functional tests into their own module. * Remove the right sidebar. * Remove the lettuce applications. * Remove extraneous files from the thefec module. Closes #367: Create Initial project
The general workflow we follow is based on A Git Workflow for Agile Teams.
Work on a new task begins by branching from
develop. Feature branch names
should be in the format of
$ git checkout -b 142-add-account-history develop
Commits on this branch should be early and often. These commit messages are not permanent and do not have to use the format specified above.
You should fetch and rebase against the upstream repository often in order to prevent merging conflicts:
$ git fetch origin develop $ git rebase origin/develop
When work is done on the task, you should rebase and squash your many commits into a single commit:
$ git rebase -i origin/develop
You may then choose which commits to reorder, squash or reword.
Only rebase commits that have not been published to public branches. Otherwise problems will arise in every other user’s local repository. NEVER rewrite public branches and NEVER force a push unless you know EXACTLY what you are doing, and have preferably backed up the upstream repository.
Afterwards, merge your changes into
develop and push your changes to the
$ git checkout develop $ git merge 142-add-account-history $ git push origin develop
Preparing a Release¶
A Release should be forked off of develop into its own branch once all
associated features are completed. A
release branch should contain only
bugfixes and version bumps.
releasebranch off of the
$ git checkout -b release-1.2.0 develop
Branch, Fix and Merge any existing bugs.
Bump the version number and year in
Commit the version changes:
$ git commit -a -m "Prepare v1.2.0 Release"
Create a new annotated and signed Tag for the commit:
$ git tag -s -a v1.2.0 The annotation should contain the release's name and number, and optionally a short description:: Version 1.2.0 Release - Trip Entry Form This release adds a Trip Entry form for Communards and a Trip Approving form for Accountants.
Merge the branch into the
masterbranch and push it upstream:
$ git checkout master $ git merge release-1.2.0 $ git push origin master $ git push --tags origin master
Make sure to merge back into the
developbranch as well:
$ git checkout develop $ git merge release-1.2.0 $ git push origin develop
You can then remove the
releasebranch from your local repository:
$ git branch -d release-1.2.0
Each release will be tagged with a version number, using the MAJOR.MINOR.PATCH Semantic Versioning format and specifications.
These version numbers indicate the changes to the public API.
The PATCH number will be incremented if a new version contains only backwards-compatible bug fixes.
The MINOR number is incremented for new, backwards-compatible functionality and marking any new deprecations. Increasing the MINOR number should reset the PATCH number to 0.
The MAJOR number is incremented if ANY backwards incompatible changes are introduced to the public API. Increasing the MAJOR number should reset the MINOR and PATCH numbers to 0.
Pre-release versions may have additional data appended to the version, e.g.
The first stable release will begin at version 1.0.0, any versions before this are for initial development and should be not be considered stable.
For more information, please review the Semantic Versioning Specification.
This documentation is written in reStructuredText and created using the
Sphinx Documentation Generator. Sphinx’s
autodoc module is used to
create the API specifications of the application by scraping
Each class, function, method and global should have an accurate docstring for Sphinx to use.
Each feature or bug fix should include all applicable documentation changes.
To build the Documentation, install the prerequisites then run the make command to generate either html or pdf output:
$ pip install -r requirements/local.txt $ cd docs/ $ make html; make latexpdf
The output files will be located in the