CONTRIBUTING.rst

How To Contribute

• Getting Started
  • Commits
  • Branches
  • Documentation
  • Testing
• Code Submission
  • Code Improvement
  • Code Submission
  • Code Review
  • Code Acceptance

Contributions to Foremast are welcome.

Getting Started

Commits

Follow semantic commits to make :command:`git log` a little easier to follow.

chore

something just needs to happen, e.g. versioning

docs

documentation pages in :file:`_docs/` or docstrings

feat

new code in :file:`src/`

fix

code improvement in :file:`src/`

refactor

code movement in :file:`src/`

style

aesthetic changes

test

test case modifications in :file:`test/`

Examples commit messages:

• chore: v10.0
• docs: Add configuration setting
• feat: Create Lambda function
• fix: Retry upload on failure
• refactor: Extract duplicate code
• style: isort, YAPF
• test: Coverage around add permissions

Branches

Use slash convention with the same leaders as :ref:`commits`, e.g.:

• chore/v10.0
• docs/configs
• feat/lambda
• fix/deadlock
• refactor/debug_util
• style/lambda_whitespace
• test/lambda_permission

Documentation

• Use reStructuredText for docstrings and documentation
• For docstrings, follow :ref:`napoleon:example_google`
• For documentation pages, follow the strong guidelines from Python with :ref:`pythondev:documenting`

Note

• Use :file:`.rst` for regular pages
• Use :file:`.rest` for pages included using .. include:: file.rest (fixes a Sphinx issue that thinks references are duplicated)

Testing

Run any unit tests available in ./tests/.

virtualenv venv
source ./venv/bin/activate
pip install -U -r requirements-dev.txt

tox
# OR
./runtests.py

Code Submission

Code Improvement

1. See if an Issue exists
   • Comment with any added information to help the discussion
2. Create an Issue if needed

Code Submission

1. See if a Pull Request exists
   • Add some comments or review the code to help it along
   • Don't be afraid to comment when logic needs clarification
2. Create a Fork and open a Pull Request if needed

Code Review

• Anyone can review code
• Any Pull Request should be closed or merged within a week

Code Acceptance

Try to keep history as linear as possible using a rebase merge strategy.

1. One thumb up at minimum, two preferred

2. Request submitter to rebase and resolve all conflicts

   # Update `master`
   git checkout master
   git pull
   
   # Update `feat/new` Branch
   git checkout feat/new
   git rebase master
   
   # Update remote Branch and Pull Request
   git push -f

3. Merge the new feature

   # Merge `feat/new` into `master`
   git checkout master
   git merge --ff-only feat/new
   git push

4. Delete merged Branch