Contributing to HSSM¶

We invite contributions to the HSSM project from interested individuals or groups. To ensure that your contributions align with the conventions of the HSSM project and can be integrated as efficiently as possible, we provide the following guidelines.

Table of Contents¶

Ways to Contribute
Opening Issues
Pull Request Step-by-Step

Ways to Contribute¶

There are three main ways you can contribute to HSSM (listed in decreasing order of scope):

Expanding the existing codebase with new features or improvements to existing ones. Use the "Feature Request" label.
Contributing to or improving the project's documentation and examples (located in hssm/examples). Use the "Documentation" label.
Rectifying issues with the existing codebase. These can range from minor software bugs to more significant design problems. Use the "Bug" label.

Opening Issues¶

If you find a bug or encounter any type of problem while using HSSM, please let us know by filing an issue on the GitHub Issue Tracker rather than via social media or direct emails to the developers.

Please make sure your issue isn't already being addressed by other issues or pull requests. You can use the GitHub search tool to search for keywords in the project issue tracker. Please use appropriate labels for an issue.

Pull Request Step-by-Step¶

The preferred workflow for contributing to HSSM is to fork the GitHub repository, clone it to your local machine, and develop on a feature branch.

Steps¶

Fork the project repository by clicking on the ‘Fork’ button near the top right of the main repository page. This creates a copy of the code under your GitHub user account.
Clone your fork of the HSSM repo** from your GitHub account to your local disk.
```
git clone https://github.com/<your GitHub handle>/lnccbrown/hssm.git
```
Navigate to your hssm directory and add the base repository as a remote. This sets up a directive to propose your local changes to the hssm repository.
```
cd hssm
git remote add upstream https://github.com/lnccbrown/hssm.git
```
Create a feature branch to hold your changes:
```
git checkout -b my-feature
```

[!WARNING] Routinely making changes in the main branch of a repository should be avoided. Always create a new feature branch before making any changes and make your changes in the feature branch.

Add the new feature/changes on your feature branch. When finished, commit your changes:
```
git add modified_files
git commit -m "commit message here"
```

After committing, it is a good idea to sync with the base repository in case there have been any changes:

git fetch upstream
git rebase upstream/main

[!Note] If your changes require libraries not included in hssm, you'll need to use Poetry to update the dependency files. Please visit the official Poetry documentation and follow the installation instructions to install Poetry on your system.

After installing Poetry, you can add the new libraries (dependencies) to pyproject.toml by running:
poetry add <package-name>
Replace <package-name> with the name of the library you need to add. This command will update the pyproject.toml file and install the new dependency. It will also add changes to the poetry.lock file.

Remember to commit the newly changed files.
git add pyproject.toml poetry.lock
git commit -m "Add <package-name> dependency"

Push the changes to your GitHub account with:
```
git push -u origin my-feature
```
Create a Pull Request:
Go to the GitHub web page of your fork of the HSSM repo.
Click the ‘Pull request’ button to send your changes to the project’s maintainers for review.

This guide is adapted from the ArviZ contribution guide