Establish a Continuous Deployment / Continuous Integration Pipeline

[xehu]

Moving forward, we need to establish a procedure that manages end-to-end updates to the package, from the moment a PR is merged in to deploying a new version of the package on PyPI. Some general requirements would be:

• For major (i.e., non-cosmetic) changes, create a "dev" branch for local testing;
• Upon merges to main, if the tests pass, deploy a new version of the package to PyPI;
• Update the release on GitHub;
• Have updated changelogs / notes for the new release.

This issue will be updated as we come up with additional details for this pipeline.

[sundy1994]

This is what I had in mind about the development workflow:

dev branch

The advantage of having a dev branch is to separate releasing and developing, especially when there are many collaborators working on different features. In that case, we only merge new releases to main to keep the history clean, while the dev branch is constantly updated and tested. However, our package is not intensively being developed so I guess whether to have it is just a matter of choice. Our development can work totally fine without it.

Continuous Integration (CI)

1. Create a new branch off the dev branch for new features / bug fixes / documentation updates
2. Develop and commit changes
3. Every commit triggers automated testing, which is exactly what we are doing now. If you want, there are some tools that help checking code quality.
4. Manual testing is probably necessary especially when new features are introduced. Update the testing workflow as well if needed.
5. Open a Pull Request to squash and merge into dev. Code review is required, you would want to provide feedback and suggest improvements. Upon merging, the auto-test runs again to ensure there's no conflict after merging. If everything works well, delete the temporary branch.

Continuous Development (CD)

1. Once the new version is ready to be released (this is probably when we have accumulated several updates in dev), open a Pull Request to squash and merge dev into main. Again, code review is required, and auto-test will be triggered. Be sure to bump the version number in pyproject.toml in this step. Optionally, a release branch can be created off dev for further testing. In that case, we merge the release branch into main instead of dev.
2. Once the PR is approved, build the package again: python -m build, publish to PyPI: twine upload dist/* (your API token is required at this step) and publish a release in GitHub. Optionally, this step can be automated by a GitHub Action which is triggered by any PRs to the main branch.

[xehu]

Notes from Emily / Yuxuan's Meeting on 8/15

We want to keep Main largely consistent with the package itself, and have a dev branch that we can push updates pretty frequently.

Decisions

• Use the dev branch and make sure it is up to date with main
• Small changes (e.g., typo fixes) can be directly committed; larger changes (e.g., new features, should go in via PR)
• Like all branches, dev branch will have automatic testing.
• If there are new features, we should also add tests accordingly.
• PR dev into main once sufficiently large amounts of new commits accumulate; main will accept PR's from dev
• In the future, set up auto-deployment through main

Steps for deployment

1. Bump the version number in pyproject.toml (we should bump 1.0.0 -> 1.0.1; last number is a "patch release;" if we publish new features/major functions, we bump the second number, "minor update," and then the first number represents a "major change")
2. python -m build (locally; this creates the wheel files)
3. twine upload dist/* (with the API token; this will upload the wheel to the PyPI repository)