In this answer, I am going to follow a step by step guide similar to what I did 9 years ago in this How to contribute to Sage talk that became outdated because of the switch from Mercurial to git. Let me first assume that your system is already set up so that you see what is the usual workflow using just bare git commands (you may also want to use the git trac subcommands to improve the workflow). I will put in italic the stuff you need to do once and for all for all your future contributions.
Step 1: Create a branch. First go to whereever your sagemath tree is:
$ cd SAGE_ROOT
Show the current branches:
$ git branch -v
* develop 6a45805 Updated SageMath version to 9.1.beta9
master 74b0302 Updated SageMath version to 8.0
Create a new branch on top of some recent [development] version of SageMath and switch to that branch:
$ git checkout develop -b my_branch
This confirms the effect:
$ git branch -v
develop 6a45805 Updated SageMath version to 9.1.beta9
master 74b0302 Updated SageMath version to 8.0
* my_branch 6a45805 Updated SageMath version to 9.1.beta9
Step 2: Edit files. Using your favorite text editor, open and edit some file[s] in the sage tree:
$ vim src/sage/rings/real_mpfr.pyx
Step 3: Test your changes. Make sure that you did not mess up anything by making sure that all doctests in that file are still passing:
$ sage -bt --long src/sage/rings/real_mpfr.pyx
If you changed the documentation, you may check that the documentation still builds fine:
$ make doc
Step 4: Commit your changes to the branch. Once you are done, you may look at a summary of files that were changed :
$ git status
$ git diff # more detailed
Do more changes if necessary. Once corrections are done, add files to the next commit:
$ git add src/sage/rings/real_mpfr.pyx
If we made a mistake, git status
also tells how to revert what we just did.
Then, we may create the commit containing what git status says it contains together with a commit message.
NOTE: A commit contains more information including date, time, author. The author information is taken from the file ~/.gitconfig
which you should create first.
$ git commit -m "fixing enumeration alignment in documentation"
Step 5: Make your branch public. The next step is to share our improvement to the community.
NOTE: If it is the first time you push some branch to the trac server, you first need to do some more administration work once and for all: create an account on SageTrac and then enable communication from our git tree to the sagetrac server with SSH.
You may make your branch public by doing:
$ git push trac my_branch:u/YOUR_TRAC_LOGIN/my_branch
You may now confirm that it worked if you see the branch here: https://git.sagemath.org/sage.git/.
Step 6: Get your branch to be reviewed. Now if you want people to take a look at your public branch, and possibly get it to be reviewed so that it eventually get into Sage, then you should create a ticket if not already existing. Then, you simply set the branch field of that ticket to u/YOUR_TRAC_LOGIN/my_branch
, see the result in ticket #29477 in my case. Once it is ready for review, you may change the status of the ticket to needs_review
.
Step 7: Conclusion. You may now want to go back to your develop branch:
$ git checkout develop
$ make # or possibly just `sage -b` is enough
You may now create new branches to make new contributions to Sage. You may also want to update your current develop branch to the most recent development version containing all positively reviewed tickets (hopefully containing yours) and build Sage using 8 cpus:
$ git pull origin develop
$ MAKE='make -j8' make