Skip to content

Commit

Permalink
Merge pull request #97 from romainmartinez/contributing
Browse files Browse the repository at this point in the history
Contributing instructions
  • Loading branch information
pariterre committed Jun 6, 2020
2 parents 98109e2 + 2e22b5a commit 86df882
Show file tree
Hide file tree
Showing 2 changed files with 91 additions and 2 deletions.
88 changes: 88 additions & 0 deletions docs/contributing.md
@@ -0,0 +1,88 @@
All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome.
We recommend going through the [`issues`](https://github.com/pyomeca/pyomeca/issues) to find issues that interest you.
Then, you can get your development environment setup with the following instructions.

## Forking Pyomeca

You will need your own fork to work on the code.
Go to the [pyomeca project page](https://github.com/pyomeca/pyomeca/) and hit the `Fork` button.
You will want to clone your fork to your machine:

```bash
git clone https://github.com/your-user-name/pyomeca.git
cd pyomeca
git remote add upstream https://github.com/pyomeca/pyomeca.git
```

## Creating a Python environment

Before starting any development, you’ll need to create an isolated pyomeca development environment:

- Install [miniconda](https://conda.io/miniconda.html)
- `cd` to the pyomeca source directory
- Install pyomeca dependencies with:

```bash
conda env create
conda activate pyomeca
pip install -r requirements-dev.txt
```

## Creating a branch

You want your master branch to reflect only production-ready code, so create a feature branch for making your changes.
For example:

```bash
git branch -b new-feature
```

Keep any changes in this branch specific to one bug or feature so it is clear what the branch brings to pyomeca.

## Testing your code

Adding tests is required if you add or modify existing codes in pyomeca.
Therefore, it is worth getting in the habit of writing tests ahead of time so this is never an issue.
The pyomeca test suite runs automatically on GitHub Actions, once your pull request is submitted.
However, we strongly encourage running the tests prior to submitting the pull request.
To do so, run `make test` or simply `pytest tests`.

## Linting your code

Pyomeca uses several tools to ensure a consistent code format throughout the project.
The easiest way to use them is to run `make lint` from the source directory.

## Making the pull-request

When you want your changes to appear publicly on your GitHub page, push your forked feature branch’s commits:

```bash
git push origin new-feature
```

If everything looks good, you are ready to make a pull request.
This pull request and its associated changes will eventually be committed to the master branch and available in the next release.

1. Navigate to your repository on GitHub
2. Click on the `Pull Request` button
3. You can then click on `Files Changed` to make sure everything looks OK
4. Write a description of your changes in the Discussion tab
5. Click `Send Pull Request`

This request then goes to the repository maintainers, and they will review the code.
If you need to make more changes, you can make them in your branch, add them to a new commit and push them to GitHub.
The pull request will be automatically updated.

!!! info "PR Checklist"

Let's summarize the steps needed to get your PR ready for submission.

1. **Use an isolated Python environment**.

2. **Properly test your code**. Write new tests if needed and make sure that your modification didn't break anything by running `make test`.

3. **Properly format your code**. You can verify that it passes the formatting guidelines by running `make lint`.

4. **Push your code and create a PR**.

5. **Properly describe your modifications** with a helpful title and description. If this addresses an issue, please reference it.
5 changes: 3 additions & 2 deletions mkdocs.yml
Expand Up @@ -15,8 +15,9 @@ nav:
- Overview: overview.md
- Getting Started: getting-started.md
- User Guide:
- Object creation: object-creation.md
- Data processing: data-processing.md
- Object creation: object-creation.md
- Data processing: data-processing.md
- Contributing: contributing.md
- About: about.md
- API reference:
Analogs: api/analogs.md
Expand Down

0 comments on commit 86df882

Please sign in to comment.