-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #610 from lnccbrown/609-docs-improve-contributingmd
609 docs improve contributingmd
- Loading branch information
Showing
1 changed file
with
74 additions
and
74 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,87 +2,87 @@ | |
|
|
||
| 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. | ||
|
|
||
| There are three main ways you can contribute to [HSSM](https://github.com/lnccbrown/HSSM) (listed in decreasing order of scope): | ||
|
|
||
| 1. Expanding the existing codebase with new features or improvements to existing ones. Use the "Feature Request" label. | ||
| 2. Contributing to or improving the project's documentation and examples (located in `hssm/examples`). Use the "Documentation" label. | ||
| 3. 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](https://github.com/lnccbrown/HSSM/issues) 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 | ||
|
|
||
| 1. 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. | ||
|
|
||
| 2. Clone your fork of the HSSM repo from your GitHub account to your local disk. | ||
| ## Table of Contents | ||
| 1. [Ways to Contribute](#ways-to-contribute) | ||
| 2. [Opening Issues](#opening-issues) | ||
| 3. [Pull Request Step-by-Step](#pull-request-step-by-step) | ||
|
|
||
| `SSH` | ||
|
|
||
| ``` | ||
| git clone [email protected]:<your GitHub handle>/lnccbrown/hssm.git | ||
| ``` | ||
| ## Ways to Contribute | ||
|
|
||
| `HTTPS` | ||
|
|
||
| ``` | ||
| git clone https://github.com/<your GitHub handle>/lnccbrown/hssm.git | ||
| ``` | ||
|
|
||
| 3. Navigate to your hssm directory and add the base repository as a remote: | ||
|
|
||
| `SSH` | ||
|
|
||
| ``` | ||
| cd hssm | ||
| git remote add upstream [email protected]:lnccbrown/hssm.git | ||
| ``` | ||
|
|
||
| `HTTPS` | ||
|
|
||
| ``` | ||
| cd hssm | ||
| git remote add upstream https://github.com/lnccbrown/hssm.git | ||
| ``` | ||
|
|
||
| 4. Create a feature branch to hold your development changes: | ||
|
|
||
| ``` | ||
| git checkout -b my-feature | ||
| ``` | ||
|
|
||
|
|
||
| > Warning: Always create a new feature branch before making any changes. Make your changes in the feature branch. It’s good practice to never routinely work on the main branch of any repository. | ||
| 5. The project uses `poetry` for dependency management. Poetry needs to be installed in its own environment. Visit the official poetry documentation at https://python-poetry.org/docs/. Follow the installation instructions provided on the documentation page to install poetry on your system. This typically involves running a specific command based on your operating system. | ||
| There are three main ways you can contribute to [HSSM](https://github.com/lnccbrown/HSSM) (listed in decreasing order of scope): | ||
|
|
||
| 6. Develop the feature on your feature branch. Add your changes using git commands, git add and then git commit, like: | ||
| 1. **Expanding the existing codebase** with new features or improvements to existing ones. Use the "Feature Request" label. | ||
| 2. **Contributing to or improving the project's documentation and examples** (located in `hssm/examples`). Use the "Documentation" label. | ||
| 3. **Rectifying issues with the existing codebase**. These can range from minor software bugs to more significant design problems. Use the "Bug" label. | ||
|
|
||
| ``` | ||
| git add modified_files | ||
| git commit -m "commit message here" | ||
| ``` | ||
| ## Opening Issues | ||
|
|
||
| To record your changes locally. After committing, it is a good idea to sync with the base repository in case there have been any changes: | ||
| 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](https://github.com/lnccbrown/HSSM/issues) rather than via social media or direct emails to the developers. | ||
|
|
||
| ``` | ||
| git fetch upstream | ||
| git rebase upstream/main | ||
| ``` | ||
| 7. Then push the changes to your GitHub account with: | ||
| Please make sure your issue isn't already being addressed by other issues or pull requests. You can use the [GitHub search tool](https://github.com/lnccbrown/HSSM/issues) to search for keywords in the project issue tracker. Please use appropriate labels for an issue. | ||
|
|
||
| ``` | ||
| git push -u origin my-feature | ||
| ``` | ||
| ## [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) Step-by-Step | ||
|
|
||
| 8. 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 will send an email to the committers. | ||
| 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. | ||
|
|
||
| ** This guide is adapted from the [ArviZ contribution guide](https://github.com/arviz-devs/arviz/blob/main/CONTRIBUTING.md) ** | ||
| ### Steps | ||
|
|
||
| 1. [**Fork the project repository**](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) 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. | ||
|
|
||
| 2. [**Clone your fork**](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) of the HSSM repo** from your GitHub account to your local disk. | ||
| ``` | ||
| git clone https://github.com/<your GitHub handle>/lnccbrown/hssm.git | ||
| ``` | ||
|
|
||
| 3. **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 | ||
| ``` | ||
|
|
||
| 4. **Create a [feature branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) 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. | ||
| 5. **Add the new feature/changes on your feature branch**. When finished, [_commit_](https://github.com/git-guides/git-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](https://python-poetry.org/docs/) and follow the installation instructions to install Poetry on your system. | ||
| > | ||
| > After installing Poetry, you can add the new libraries (dependencies) to [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#writing-your-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`](https://python-poetry.org/docs/basic-usage/#committing-your-poetrylock-file-to-version-control) file. | ||
| > | ||
| > Remember to commit the newly changed files. | ||
| > ``` | ||
| > git add pyproject.toml poetry.lock | ||
| > git commit -m "Add <package-name> dependency" | ||
| > ``` | ||
| 6. **[Push](https://github.com/git-guides/git-push) the changes to your GitHub account** with: | ||
| ``` | ||
| git push -u origin my-feature | ||
| ``` | ||
| 7. **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](https://github.com/arviz-devs/arviz/blob/main/CONTRIBUTING.md)** | ||