How To Contribute

Contributions to Foremast are welcome.

Getting Started

Commits

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

chore
something just needs to happen, e.g. versioning
docs
documentation pages in _docs/ or docstrings
feat
new code in src/
fix
code improvement in src/
refactor
code movement in src/
style
aesthetic changes
test
test case modifications in 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 Commits, e.g.:

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

Documentation

Note

  • Use .rst for regular pages
  • Use .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