Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

609 docs improve contributingmd #610

Merged
merged 10 commits into from
Dec 13, 2024
Merged

609 docs improve contributingmd #610

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f0b59fe
Add Table of Contents
cpaniaguam Dec 12, 2024
8c446f6
Enhance contributing guidelines with bold formatting for clarity
cpaniaguam Dec 12, 2024
ec3e546
Improve formatting and enhancing links
cpaniaguam Dec 12, 2024
1222e09
Update Pull Request section with a link and improved heading format
cpaniaguam Dec 12, 2024
c2a7e28
Enhance contributing guidelines with improved formatting and links fo…
cpaniaguam Dec 12, 2024
2d12d30
Enhance contributing guidelines by adding a link to feature branch cr…
cpaniaguam Dec 12, 2024
8ee121c
Update warning
cpaniaguam Dec 12, 2024
2f2ca71
Enhance contributing guidelines with instructions for managing depend…
cpaniaguam Dec 12, 2024
4eaac02
Enhance contributing guidelines by improving the Pull Request section…
cpaniaguam Dec 12, 2024
06ba2df
Remove final sentence
cpaniaguam Dec 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 74 additions & 74 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)**

Loading