Contributing guidelines & workflows

General remarks

• Make sure to follow the PEP 8 styleguide if you make any changes to Cobra (we plan use the Black linter).
• You should also write or modify unit tests for your changes. For mocking, we use the library pytest-mock, install it with pip install pytest-mock.
• We are using templates when submitting a PR or Issue, please follow them.
• Make sure you add the Issue number with # to the commit message.
• For versioning, we are following the rules of semantic versioning.
• We are following the Gitflow workflow.

Contribution from outside of Python Predictions

The preferred way to contribute to Cobra is to fork the main repository on GitHub, then submit a "pull request" (PR). The first step is to get a local development copy by installing Cobra from source through the following steps:

• Fork the project repository. For more details on how to fork a repository see this guide.
• Clone your fork of Cobra's repo.
• Open a shell and navigate to the folder where this repo was cloned in.
• Once you are in the folder, execute pip install --editable ..
• Create a feature branch to do your development.
• Once you are finished developing, you can create a pull request from your fork (see this guide for detailed instructions).
• To avoid duplicating work, it is highly recommended that you search through the issue tracker and/or the PR list. If in doubt, you can always reach out to us through email (cobra@pythonpredictions.com).

Contribution from our team members

• Pull latest version of development branch to your local repository.
• Create a feature branch from the develop branch (follow the correct naming).
• Push your feature branch to the remote and request pull request (PR).
• PR has to have at least one reviewer. Once your PR has been approved, your work is done.
• After, the feature branch can be deleted.

Release workflow

Once we decide to wrap-up a milestone (see https://github.com/PythonPredictions/cobra/milestones), we create a release, with the following steps:

1. Verify whether all urgent/necessary issues linked to the current milestone have been closed (solved by a pull request).
2. Postpone any remaining issues on the current milestone to one of the next milestones.
3. Clean up the milestone project dashboard as a final check of the status of all issues linked to the milestone.
4. Merge the master branch into the develop branch first (!) to avoid polluting the master branch (see explanation). Merge branches in this procedure with a pull request, such that the changes made can be discussed and reviewed in the development team.
5. Now merge the develop branch into master, again with a pull request. Be sure, when having to make last-minute fixes, for example, to make the unit tests pass, that you run and test cobra locally on the latest requirements.txt and requirments.dev.txt.
6. Wait for the pull request to be reviewed and finally approved. You may need to do some fixes on request of the pull request reviewer before the merge development -> master can finally be approved and done.
7. Tag the master branch to prepare for the new release, see these steps: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository. The tag creation page will allow you to include an auto-generated changelog. Write a more high-level summary of the included changes above that, readable for less technically experienced users. You can inspire yourself on the preceding releases.
8. The GitHub Actions build pipeline will build the distribution archives for Cobra and release them on PyPI.

• General information about what happens here: https://docs.github.com/en/actions/guides/building-and-testing-python#publishing-to-package-registries).
• The actual publishing of the package in the end is done with the GitHub action pypa/gh-action-pypi-publish, as you may notice in our master_publish_pypi.yaml file. This step picks up our PyPI username and password from a token configured in Cobra's project settings, which allows for the build pipeline to finish the upload of the package autonomously.
• If the above fails, fix the build pipeline or perform a manual release as an alternative. For performing the manual release, you'll need to provide our PyPI username and password yourself, you can find them on our internal Python Predictions wiki's Cobra page.

9. Close the current milestone: https://github.com/PythonPredictions/cobra/milestones
10. Close the milestone project dashboard and create a new one for the new monthly release milestone. Review the planned issues for the newly started monthly release.

GitHub Actions

• development_CI.yaml: CI/CD pipeline for linting & unit testing whenever we push to the develop branch.
• master_CI.yaml: CI/CD pipeline for linting & unit testing whenever we push to the master branch.
• master_publish_pypi.yaml: build pipeline which will build the distribution archives from the master branch, including the latest changes, and upload it to PyPI. For more details, see the Release workflow section above on this page.