Contributing

Instructions for contributors

Make a clone of the bitbucket repo:

git clone https://github.com/cmalek/sungazer.git

Workflow is pretty straightforward:

Make sure you are reading the latest version of this document.
Setup your machine with the required development environment
Make your changes.
Update the Sphinx documentation to reflect your changes.
cd doc; make clean && make html; open build/html/index.html. Ensure the docs build without crashing and then review the docs for accuracy.
Commit changes to your branch.
Merge your changes into master.
make release.

Preconditions for working on this project

Python environment

Install your Python environment with the following:

MacOS and Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
Now add the following to your ~/.bash_profile or ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
Then run:

Testing out sungazer

To test out your changes to sungazer, you can run the following command:

sungazer shell

This will start an ipython shell with all botocraft service classes loaded. You can then run commands like:

service = Service.objects.get('my-service', cluster='my-cluster')

Important

The important part here is that the shell loads completely without any namespace or circular import errors. If you see any errors, then you need to fix them before proceeding.

Updating the documentation

As you work on the app, put some effort into making the Sphinx docs build cleanly and be accurate.

doc/source/index.rst

Check the “Overview” section and maybe update if you’ve added some big new features
Check the “Important People” section and update as appropriate
Check the “History” section and update as appropriate

autodoc

The api documentation is automatically generated from the docstrings in the generated code, so there’s nothing to do here for any code that gets generated into botocraft.services.

For your own code (e.g. anything in botocraft.mixins, botocraft.sync and botocraft.eventbridge), please add appropriate documentation to your classes, methods and attributes as docstrings, add them if appropriate to files in doc/source/api/.

etc.

Review the other files to see if they need updating.

Then build the docs and look at them:

cd doc
make clean && make html
open build/html/index.html

Warning

This will take a looooong time, because the service docs are huge.

If you can build the docs with no critical errors and the docs seem to look ok when you look through all the HTML pages, that’s good enough at this point.

Releasing the code to PyPI

When you’re ready to release the code to PyPI, if you’re on a branch:

git checkout master
git pull
git checkout <branch>
git rebase master
git checkout master
git merge <branch>

This will pull anyone else’s changes into your branch and then merge your branch into master.

Then run the following command to bump the version number and create a new distribution in PyPI:

bumpversion <patch|minor|major>
make release