Skip to content

Latest commit

 

History

History
132 lines (96 loc) · 4.88 KB

general-contributing-guide.md

File metadata and controls

132 lines (96 loc) · 4.88 KB
Raw

General Contributing guidelines

This is a general (short) guide on how to contribute to open-source projects. Please make sure to read the specific contributing guidelines of the project you want to contribute to!

Index

  1. How to contribute? Step by step guide
  2. PR conventions
  3. PR review rules
  4. Issue guidelines
  5. References

How to contribute? Step by step guide

Glossary

  • Upstream: the repository from the original_author
  • Origin: the forked repository under your account

Steps

1. Fork a project with your GitHub account

2. Clone the project to your local environment

git clone https://github.com/account/project.git
cd project

3. Set up the origin and upstream of the your local project

#  Add the "upstream" to your cloned repository
git remote add upstream https://github.com/original_author/project.git

# Add the "origin" to your cloned repository
git remote add origin https://github.com/account/project.git

4. Work in a new branch of your origin

# 1) Create a new branch (e.g. `my-new-branch` from your origin/main branch
git branch my-new-branch origin/main
git checkout my-new-branch

# 2) Make your changes to the code

# 3) Add the modified files and make a commit (e.g. you updated README.md)
git add README.md
git commit -m 'added a better description'

# 4) Push to your new-branch
git push origin my-new-branch

5. Make a pull request on GitHub

  • Go to the my-new-branch of your forked project on Github
  • Click Compare & pull request
  • Leave a comment
    • If you are solving an issue (e.g. #17), add Closes #17 in the comment, the issue will automatically be closed when the pull request is merged.

6. Delete branch locally and/or remotely after pull request is merged on GitHub

  • Deleting your local branch from the command line: git branch -d my-new-branch
  • Additionally if you want to delete your remote branch: git push origin : my-new-branch

7. (in case you need it) Synchronize with updates from the upstream

Sometimes you may need to update your fork with the latest changes from the upstream. This may happen when, for example, the main branch was update since you opened your PR and contains conflicts with your changes .

# 1) Go to the "my-new-branch" branch of your fork ("origin")
git checkout my-new-branch

# 2) Fetch the commits from the "upstream"
git fetch upstream

# 3) Merge the changes from the "main" branch of the "upstream" into your the "my-new-branch" branch of your "origin"
git merge upstream/main

# 4) Resolve merge conflicts if any and commit your merge
git commit -m "Merged from upstream"

# 5) Push the changes to your fork ("origin")
git push

PR conventions

⚠️ Note: these conventions varies from project to project. Please check the contributing guidelines of the project you want to contribute to.

When submitting a PR, please add one of the following prefixes depending on the topic you are addressing:

[ENH]: Enhancement, new functionality
[BUG]: Bug fix
[DOC]: Additions/updates to documentation
[TST]: Additions/updates to tests
[BLD]: Updates to the build process/scripts
[PERF]: Performance improvement
[CLN]: Code cleanup

In addition:

  • Please reference the relevant GitHub issues in your commit message using GH1234 or #1234.
  • Include a subject line with < 80 chars.
  • Optionally, include a commit message body, leaving one blank line with the subject line.

PR review rules

Projects require the input from one or more reviewers to merge a pull request. For example, one reviewer approves the merge and the other reviewer merges the pull request.

Issue guidelines

New issue

Discovering an issue is great, here's what you need to do when you discover an issue:

  • Search if the issue has already been created.
  • If yes and open refer to existing issue.
  • If yes and closed reopen issue with descriptive comment.
  • If no, create the issue.

Existing issue

  • Read comments.
  • Find out if anyone is working on it, if no, offer to do it. If yes, see if you can be of help.

Reporting bugs

  • Give information about the version and the operating system you are running.
  • Show the steps to reproduce bug.
  • Add error logs.

References

Main resource: https://github.com/python-sprints/pandas-mentoring/blob/master/contributing.md