Contribution Guidelines

Contents

• Contribution Guidelines

  • Release cycle

  • Code formatting

  • Initialization

  • Building the docs

  • Coverage

  • Pull Requests Checklist

• Documentation Convention
  • Basics
  • Imports
  • Building the docs
  • Common Sense Boosters
  • Structure
  • Example of Docstring
  • Configuration
• Sprinting PyCon US 2019
  • Initialization

Release cycle

• Master branch commits are automatically packaged and published to PyPI.

• We follow both Semantic Versioning pattern and PEP440 recommendations where comply

• Branches for planned staging versions follow the pattern: X_Y_Z (Major.Minor.Micro)

• Make your pull requests go to the closest staging branch (with smallest after release number of either current or next Minor)

• Make sure your branch is up to date with the branch you are making a PR to

Example:

• Latest released version in PyPI 0.7.31

• Closest staging Minor branch in sosw/sosw 0_7_33

• Latest Minor staging branch in sosw/sosw 0_7_35

• Closest Next Minor branch in sosw/sosw 0_9_1

Your PR should be to either 0_7_33 or 0_9_1 depending on the importance of changes.

Code formatting

• follow the PEP8 with the following details:

• both classes and functions are padded with 2 empty lines

Initialization

• Fork the repository: https://github.com/sosw/sosw

• Register Account in AWS: SignUp

• Run pipenv sync --dev to setup your virtual environment and download the required dependencies

• If you are not familiar with CloudFormation, we highly recommend at least learning the basics from the tutorial.

• Follow the Installation to setup your environment.

• Create some Sandbox Lambda.

• Play with it.

• Read the Documentation Convention

Building the docs

To build the docs locally, run: sphinx-build -Wab html ./docs ./sosw-rtd

You can also use the built in python web server to view the html version directly from localhost in your preferred browser.

sphinx-build -Wab html ./docs ./sosw-rtd; (cd sosw-rtd && python -m http.server)

Coverage

We use pytest-cov for calculating the test coverage. Currently there is no automatic blocker for untested code. In order to calculate the actual coverage you have to run it will all the integration tests, so this is mainly used during release.

.converagerc holds the configuration for Coverage module.

pytest --cov=sosw sosw/
rm  docs/_static/images/coverage.svg; coverage-badge -o docs/_static/images/coverage.svg

Pull Requests Checklist

Great that you are ready to contribute!

• Make sure your fork is up to date with upstream

# Clean everything
git reset --hard
git clean -fdx
git checkout master

# Fetch possible changes to YOUR master
git pull origin master

# Check if remote upstream is configured
git remote -v

# If missing upstream
git remote add upstream https://github.com/sosw/sosw

# Update your fork remote with the upstream changes
git pull upstream master
git push origin master

• Make sure your code passes all the tests

pytest sosw/test/suite_unit.py

• Make sure the documentation builds correctly

sphinx-build -ab html ./docs ./sosw-rtd; (cd sosw-rtd && python -m http.server)

• Push the changes to your fork remote

git push origin master

• Make a PR to the upstream repository of sosw

Some guidelines of how to do create PRs from forks can be found in GitHub documentation.