Developer Documentation

Developer Documentation#

We welcome any contributions and collaboration on our development efforts, which are hosted on GitHub. Below are the different ways you can contribute and the steps to get involved.

Contributing Code or Documentation#

New to contributing code on GitHub? We recommend reviewing the AstroPy developer documentation to get familiar with the workflow. The most important first step is to get comfortable with the git version control system and the GitHub platform. Additionally, we highly recommend making many small commits with clear commit messages (following the Conventional Commit structure described below), as this makes it easier to review and understand your changes.

Setting Up Your Development Environment#

1. Clone the Repository:#

Clone the repository to your local machine using the shell command

git clone git clone https://github.com/HWO-Yield-Visualizations/yieldplotlib.git

Next, navigate to the repository directory and create a new branch:

cd yieldplotlib
git checkout -b BRANCHNAME

Replace BRANCHNAME with a descriptive name for your contribution.

2. Create an Isolated Development Environment:#

Python development typically uses virtual environments to isolate dependencies for different projects, ensuring that each project has its own specific package versions without conflicts. Set up an isolated environment using venv, virtualenv, uv, conda, or a similar tool. We recommend venv or conda if you are unfamiliar with this process which can be used as follows:

venv #
python3 -m venv .venv
source .venv/bin/activate

That creates a new “virtual environment” in the .venv directory and activates it. Now when you run python commands it will not be from your system level python installation, but from the one in the .venv directory. To deactivate the environment, run deactivate from your shell.

Next if using a pip based environment, which venv and virtualenv are, install the developer dependencies as follows:

python -m pip install -U pip
python -m pip install -U -e ".[dev]"
conda #
conda create -n ypl
conda activate ypl

Here we have named our environment ypl, but you can theoretically name it whatever you like.

That creates a new “virtual environment” in the conda/envs directory and activates it. Now when you run python commands it will not be from your system level python installation, but from the one in the envs/bin directory. To deactivate the environment, run deactivate from your shell.

Now install the developer dependencies as follows:

conda install pip
python -m pip install -U -e

Note: If you would like to run the pytests or build the docs, the dependencies for those features are optional and should be installed by running the previous command but adding .[docs] or .[test].

3. Install pre-commit hooks#

We use pre-commit hooks to automatically format code and check for common errors before you commit changes. To install these hooks, run the following commands:

pip install pre-commit
pre-commit install --hook-type commit-msg

This will automatically run the hooks before each commit. If any of the hooks fail, the commit will be aborted and it will tell you what needs to be changed. It may fix the error itself, in which case you will see a line - files were modified by this hook. You can also run the hooks manually with pre-commit run --all-files.

Making Contributions#

Our project is structured like a typical Python project, with the module root in the src/yieldplotlib directory to prevent import issues and enforce a clear separation between the source code and other files such as configuration, documentation, and tests. Here are some key areas to help you get started:

Conventional Commits and Semantic Versioning#

TL;DR#

When making a commit (or pull request!) use a message that follows the structure of type(scope): message. For example,

  • feat(plotting): add new feature X

  • fix(plotting): fix bug Y

  • docs(tutorials): update documentation for Z

  • test: add test for W

  • chore: update CI/CD configuration

  • style(plotting): format code with ruff

  • refactor(plotting): refactor code for readability

In the command line, this would look like:

git add src/yieldplotlib/file_with_feat_X.py
git commit -m "feat(plotting): add new feature X"
type#

The type is required and should be one of the following:

  • feat: A new feature

  • fix: A bug fix

  • docs: Documentation changes

  • test: Adding or updating tests

  • chore: Changes to the build process or auxiliary tools

  • style: Changes that do not affect the meaning of the code (white-space, formatting, etc)

  • refactor: A code change that neither fixes a bug nor adds a feature

  • perf: A code change that improves performance

  • ci: Changes to our CI/CD configuration

  • build: Changes that affect the build system or external dependencies

(scope)#

The (scope) is optional, but should be used when the commit message is unclear without it.

All commits must be “atomic” and thus able to be described by a singular type and scope with few (rare) exceptions.

Breaking changes#

If you’re making a change that is incompatible with the current version (e.g. removing a feature, changing a function call, etc), you should also include an exclamation point at the end of the commit message, like so: feat(plotting)!: add new feature X to indicate that this is a breaking change, which will trigger a major version bump in the next release.

Why?#

This convention allows us to quickly understand the contents of a commit and automatically generate

  • The version number for the package based on semantic versioning

  • The changelog for the package based on the commit messages

  • The release notes for the package based on the commit messages

  • A new distributable version of the package that is pushed to PyPI

  • A new release of the package to GitHub

Semantic Versioning#

We use semantic versioning to manage releases. This means that the version number of the package is incremented based on the type of changes made. The version number is generated by release-please and our build backend Hatch creates a _version.py file to store the version number. You never need to manually edit the version number.

The version number is structured as MAJOR.MINOR.PATCH. An example of this is 1.2.3, where 1 is the major version, 2 is the minor version, and 3 is the patch version.

Misc#

If you’re unsure about the type of commit, use chore as a catch-all and we can help you decide the correct type.

Tutorials#

Tutorials are written in Jupyter Notebooks. Tutorial files are located in the docs/tutorials directory as .ipynb files. To edit these files and run them using your virtual environment, you’ll need to add the kernel to Jupyter. To do so, run the following commands:

source .venv/bin/activate # Activate your virtual environment
pip install jupyter
pip install ipykernel
python -m ipykernel install --user --name=venv --display-name="yieldploltlib" # Add the kernel to the Jupyter server
jupyter-notebook # Start the Jupyter Notebook server

When contributing a new tutorial, follow the format of existing ones and add a link to the tutorial in the docs/index.md file so that it is included in the documentation site.

Testing Your Contributions#

When adding a new feature or fixing a bug, include at least one test to verify the behavior of your code. Before submitting a pull request, run all unit tests with the following command:

python -m pytest -v tests

We appreciate your contributions and look forward to collaborating with you!

Contents