How to contribute with a pull request

The following details suggested steps for making your own contributions to the project using GitHub

1. Fork on GitHub: login/create an account and click the 'Fork' button at the top right corner of https://github.com/python-control/python-control/.

2. Clone to computer (Replace [you] with your Github username):

   git clone https://github.com/[you]/python-control.git
   cd python-control
   

3. Set up remote upstream:

   git remote add upstream https://github.com/python-control/python-control.git
   

4. Start working on a new issue or feature by first creating a new branch with a descriptive name:

   git checkout -b <my-new-branch-name>
   

5. Write great code.

   • Suggestion: write the tests you would like your code to satisfy before writing the code itself. This is known as test-driven development.
   • See coding conventions and testing conventions for more information

6. Run tests and fix as necessary until everything passes:

   pytest -v
   

   (for documentation, instead run touch *.rst; make html in doc directory)

7. Commit changes:

   git add <changed files>
   git commit -m "commit message that describes what changed"
   

8. Update & sync your local code to the upstream version on Github before submitting (especially if it has been a while). First go to your local branch on github.com and click sync fork at the top right of the screen. Then:

   git checkout main; git fetch --all; git merge origin/main
   git push
   

   and then bring those changes into your branch:

   git checkout <my-new-branch-name>; git rebase main
   

9. Push your branch to GitHub:

   git push origin <my-new-branch-name>
   

   (The first time you run this command you will need to use the following):

   git push --set-upstream origin <my-new-branch-name>
   

10. Issue pull request to submit your code modifications to Github by going to your fork on Github, clicking Pull Request, and entering a description.

11. Other developers will provide commentary and any suggested improvements on Github. Repeat steps 5-9 until feature is complete. When the administrators are happy with your pull request, they will "merge" it into the main repository, congratulations!

12. To create the next pull request, move to your main branch, update it to the current upstream version:

    git checkout main; git fetch --all; git merge upstream/main
    

    and then go to step 4.

If you have any git troubles such as a merge failure, this site has some more background on git: https://wiki.diasporafoundation.org/Git_workflow