# cookiecutter-python-library
Cookiecutter for spinning up new Python libraries.

## Getting Started

0. Make sure you've followed the steps to [install Poetry](https://python-poetry.org/docs/#installation).
1. Clone this repo `git clone git@github.com:theorchard/cookiecutter-python-library.git`
2. Run `make cookies` and follow the prompts. This will fill out a template using your inputs to create the start of your new Python Library!
3. Create a Github Repo for your new Python Library, using [`terraform-infra`](https://github.com/theorchard/terraform-infra/tree/master/prod/github). Some things to note as you are configuring the [`terraform-github`](https://github.com/theorchard/terraform-github) module:
* Our convention is to prefix the Github Repo name with `python-` to indicate that it is a Python Library.
* Make sure you have specified `branch_protection_enforce_admins = false`. This allows Jenkins to push a commit containing the updated library version and to push git tags to the Github Repo. 
4. Move the output of this cookiecutter (everything inside the new directory) to your new Github Repo and send off your first PR.

## Building/Packaging/Publishing Your Library

* We have a private PyPI repository at [pypi.theorchard.io](https://pypi.theorchard.io) (currently only available if you are on our VPN).
* We use [Jenkins Pipeline](https://pipeline.theorchard.io/job/publish-pypi-package-v2/) to build/publish new versions of our Python Libraries.

To get Jenkins Pipeline ready for your new Github Repo / Python Library to use Poetry (because historically we used pip etc), make a PR to [`python-deployment-utils`](https://github.com/theorchard/python-deployment-utils/blob/master/pypi/docker/entrypoint.sh)

Add your Github Repo's name to the list of `poetry_repos`.

For example, if your Github Repo is `python-dogs-rule`:

```sh
# pypi/docker/entrypoint.sh
...
log 'Running environment customizations'

poetry_repos=('python-owsclient' 'python-pdp-sdk' 'python-dogs-rule')
...
```

### Versioning Your Library

We use semver.

* When using Jenkins to build/publish, you can indicate `major`, `minor`, `patch` to create a new release candidate (rc).
* Should you need to release a new release candidate, indicate `rc`.
* Finally, when you are ready to publish an official release, you can use `release`.

Jenkins will automatically push the semver tag to the Github Repo. To make it nice for clients of the Python Library, we recommend using Github's Create a Release feature from the pushed tag. It can autogenerate release notes based on the commit message. You can also use the Create a Release page to indicate any Breaking Changes, and Upgrade/Migration Notes.

Permissions Platform team has [written a bit](https://www.notion.so/SPIKE-python-owsrequest-branching-tagging-releasing-strategy-PP-487-e235d8d6903b461d859cd027ba2b1ee1) on how to introduce major breaking changes, but still support patching prior major versions. You can choose to use this approach, or your own.