From f0b59febc53d990b68973c36d4a25dadf2463e70 Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:18:36 -0500 Subject: [PATCH 01/10] Add Table of Contents --- docs/CONTRIBUTING.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index d9c60efc..6d7adc5d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,6 +2,13 @@ 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 +1. [Ways to Contribute](#ways-to-contribute) +2. [Opening Issues](#opening-issues) +3. [Pull Request Step-by-Step](#pull-request-step-by-step) + +## Ways to Contribute + 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. From 8c446f6cd1693cd1f6ffd43435121468a2eb4e7b Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:19:06 -0500 Subject: [PATCH 02/10] Enhance contributing guidelines with bold formatting for clarity --- docs/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 6d7adc5d..b8c3cd67 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -11,9 +11,9 @@ We invite contributions to the HSSM project from interested individuals or group 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. +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: From ec3e546beef5c6affef1d1a22c3b786f7fd78b21 Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:19:51 -0500 Subject: [PATCH 03/10] Improve formatting and enhancing links --- docs/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index b8c3cd67..0930f193 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -15,11 +15,11 @@ There are three main ways you can contribute to [HSSM](https://github.com/lnccbr 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: +## 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. +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. +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. # Pull Request Step-by-Step From 1222e09c98b8078ef637026791dad4751eb8f193 Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:20:25 -0500 Subject: [PATCH 04/10] Update Pull Request section with a link and improved heading format --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 0930f193..11661df3 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -21,7 +21,7 @@ If you find a bug or encounter any type of problem while using HSSM, please let 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. -# Pull Request Step-by-Step +## [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 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. From c2a7e28e182e172b08628daa669df1bb2c771364 Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:21:07 -0500 Subject: [PATCH 05/10] Enhance contributing guidelines with improved formatting and links for clarity --- docs/CONTRIBUTING.md | 41 +++++++++++------------------------------ 1 file changed, 11 insertions(+), 30 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 11661df3..32c8db5a 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -25,39 +25,20 @@ Please make sure your issue isn't already being addressed by other issues or pul 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 +### 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. +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 of the HSSM repo from your GitHub account to your local disk. +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//lnccbrown/hssm.git + ``` -`SSH` - - ``` - git clone git@github.com:/lnccbrown/hssm.git - ``` - -`HTTPS` - - ``` - git clone https://github.com//lnccbrown/hssm.git - ``` - -3. Navigate to your hssm directory and add the base repository as a remote: - -`SSH` - - ``` - cd hssm - git remote add upstream git@github.com:lnccbrown/hssm.git - ``` - -`HTTPS` - - ``` - cd hssm - git remote add upstream https://github.com/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 to hold your development changes: From 2d12d3076881cc26ee7462ce4f6a915deac89380 Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:21:18 -0500 Subject: [PATCH 06/10] Enhance contributing guidelines by adding a link to feature branch creation and improving formatting --- docs/CONTRIBUTING.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 32c8db5a..b0151a47 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -40,11 +40,10 @@ The preferred workflow for contributing to HSSM is to fork the GitHub repository 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 -``` +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: 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. From 8ee121c9e5c0d0b106c9f5967d64f4d03ce7db1a Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:21:36 -0500 Subject: [PATCH 07/10] Update warning --- docs/CONTRIBUTING.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index b0151a47..1251fb19 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -45,17 +45,14 @@ The preferred workflow for contributing to HSSM is to fork the GitHub repository 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. -> 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. - -6. Develop the feature on your feature branch. Add your changes using git commands, git add and then git commit, like: - -``` -git add modified_files -git commit -m "commit message here" -``` +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" + ``` 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: From 2f2ca7172c9d27594206aab83d8c1a926fdc562a Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:21:58 -0500 Subject: [PATCH 08/10] Enhance contributing guidelines with instructions for managing dependencies using Poetry --- docs/CONTRIBUTING.md | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1251fb19..105ee588 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -54,17 +54,31 @@ The preferred workflow for contributing to HSSM is to fork the GitHub repository git commit -m "commit message here" ``` -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: - -``` -git fetch upstream -git rebase upstream/main -``` -7. Then push the changes to your GitHub account with: + 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 + ``` -``` -git push -u origin my-feature -``` +> [!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 +> ``` +> Replace `` 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 dependency" +> ``` + +6. **[Push](https://github.com/git-guides/git-push) the changes to your GitHub account** with: + ``` + git push -u origin my-feature + ``` 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. From 4eaac024da65a30848aa14b56adddffca96421ab Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:22:12 -0500 Subject: [PATCH 09/10] Enhance contributing guidelines by improving the Pull Request section formatting --- docs/CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 105ee588..3f4981ba 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -80,7 +80,9 @@ The preferred workflow for contributing to HSSM is to fork the GitHub repository git push -u origin my-feature ``` -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. +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 will send an email to the committers. -** This guide is adapted from the [ArviZ contribution guide](https://github.com/arviz-devs/arviz/blob/main/CONTRIBUTING.md) ** +**This guide is adapted from the [ArviZ contribution guide](https://github.com/arviz-devs/arviz/blob/main/CONTRIBUTING.md)** From 06ba2df4a7ab0c3cc8d59af60cd886e854731676 Mon Sep 17 00:00:00 2001 From: Carlos Paniagua Date: Wed, 11 Dec 2024 22:28:26 -0500 Subject: [PATCH 10/10] Remove final sentence --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3f4981ba..d4512d3c 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -82,7 +82,7 @@ The preferred workflow for contributing to HSSM is to fork the GitHub repository 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 will send an email to the committers. + - 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)**