Skip to content

Latest commit

 

History

History
140 lines (110 loc) · 6.29 KB

CONTRIBUTING.md

File metadata and controls

140 lines (110 loc) · 6.29 KB
Raw

Contributing

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

"Short-lived, single feature branches are the way to go."

Keep your changes focused on a single feature. Don't try to solve several unrelated issues in the same pull request. This makes reviewing changes impractical. If your branch is not short-lived, there is also a high probability that you will need to rebase it before submitting your changes for review.

"Never push changes directly to the main branch, even if you have permissions."

Several continuous integration workflows are configured for the repository, they need to pass successfully before considering merging modifications into the main branch.

1. Create your fork and local clone of the repository

  • Go to BCDI's repository on GitHub. Click on the “Fork” button. This will create a fork of BCDI on your GitHub repository.
  • Click on the “Code” button. Select “HTTPS” is selected, unless you’ve set up SSH. Click on the clipboard icon to copy the address.
  • Open a terminal. Navigate to a directory where you want to put your repository.
  • Clone your fork of BCDI to your local computer: git clone https://github. com/your-name/bcdi.git. This will create a BCDI subdirectory inside the directory you were already in.
  • Activate your Python environment and install the dependencies: python -m pip install -r requirements.txt

Note on virtual environment

For contributors, it is recommended not to install the bcdi package in your virtual environment, but rather tell python where to look for it:

  • Modify your virtual environment script:
    • Linux: in venv/bin/activate, add export PYTHONPATH="$PYTHONPATH:path_to/bcdi"
    • Windows: in venv\Scripts\activate.bat, add set PYTHONPATH=$PYTHONPATH;path_to\bcdi
  • Confirm with an python , import bcdi.

2. Make your local clone track the original upstream repository.

(This is optional but useful if you plan to make more than one contribution)

  • Synchronize your local clone with the original repository (you can use a different name from upstream, though it is a common usage): git remote add upstream https://github.com/carnisj/bcdi.git
  • Check the remotes with git remote -v. There should be origin (which corresponds to your fork) and upstream (which corresponds to the original repository)

3. Update your local clone with the latest changes from the upstream repository

  • Be sure that you are on your main branch: git checkout main
  • Fetch the most recent changes from remotes: git fetch --all
  • Merge the upstream changes into your own project: git rebase upstream/main
  • Push the changes to your fork on GitHub: git push origin main (if git complains use the option --force-with-lease)

4. Work on your new feature and create a pull request

  • Do not work on your main branch, but create a feature branch and give it a descriptive name. This command will create the branch, and switch you to it: git checkout -b branch-name
  • To check the branches that you have and which branch you are on, type: git branch
  • Push and link the branch to your fork on GitHub: git push --set-upstream origin branch-name
  • Edit a file, for example filename.py, add tests, and make sure the tests still pass.
  • Run automated tasks: in a terminal, go to the same level as dodo.py and simply type: doit. This will run a series of tasks, including tests with coverage, code formatting, docstring and documentation checks...
  • Commit the file and push it to GitHub:
    • git add filename.py
    • git commit -m "Add exciting new feature"
    • git push

5. Create a pull request

  • If they were several changes committed to the upstream main branch while you were working on your feature branch, you may want/need to rebase your branch (to get a clean history). For this, you need to:
    • Update your local main branch (section 3). This should be a simple fast-forward merge since you never committed to your main branch. If you did commit to your main branch, see * below.
    • Rebase your feature branch on your main branch (note that there may be conflicts, if the upstream main changes affect the same portion of code as yours):
      • git checkout branchname
      • git rebase main
      • git push --force-with-lease origin branchname
  • Submit a pull request.
  • Wait for your pull request to be reviewed and merged.

* If you committed to your main branch, you need first to rebase it on the upstream main:

  • git fetch upstream
  • git checkout main
  • git rebase upstream/main
  • git push --force-with-lease origin main

6. Delete your feature branch and start over

  • Once your pull request has been merged, delete the local and remote branches:
    • Switch to your local main branch: git checkout main
    • Delete the remote branch: git push origin :branch-name
    • Delete the local branch: git branch -D branch-name
    • You may have to clean the stale branch: git remote prune origin
  • Start over at section 3.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Follow the style guide (PEP 8 recommendations).
  • Write and update tests.
  • Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
  • Write a good commit message.

Work in Progress pull requests are also welcome to get feedback early on, or if there is something that blocked you.

Resources