Wiki

Clone wiki

petsc / pull-request-instructions-git

Creating a Pull Request for Your New Functionality using git

Use this method if you don't have write access to the PETSc repository. Sending a pull request requires a free account here at bitbucket, so please sign up if you haven't already.

Clone the Repository

If you haven't already, the first step is to obtain a recent copy of the PETSc repository:

 $> git clone https://bitbucket.org/petsc/petsc.git
 $> cd petsc/

This creates a new folder 'petsc' containing the development repository and changes right into it.

Branch From Master

Make sure you start your development from the latest master branch (if you are providing an error fix for the release version of PETSc then you should checkout the branch maint) by running

 $:petsc> git checkout master
 $:petsc> git pull

on a clean working tree. Create a new branch with a name of your choice (avoid spaces), e.g. yourname/short-feature-name by

 $:petsc> git checkout -b yourname/short-feature-name

Apply your Changes

Start developing your feature on the new branch. Ideally, apply self-contained commits once in a while using expressive commit messages. A single large commit at the end of the development process makes it much harder to track down any bugs showing up at a later point in time, particularly after your contribution is merged back to PETSc.

Commit your Changes

First check a summary of changed files:

  $:petsc> git status

If all the files shown as 'modified' should indeed be commited, issue

  $:petsc> git commit -a

On the other hand, if you want to select specific files to include in the commit, or if you added new files, specify them via:

  $:petsc> git add path/to/file1 path/to/file2

and commit them using

  $:petsc> git commit

Write good commit messages.

Fork the PETSc repository on Bitbucket

Once you completed your work on yourname/short-feature-name with a final commit message, it is time to publish your contributions. Make sure you are logged in with your username on Bitbucket. You should then see the button Fork in the upper right, just next to 'Clone'. You will then see a form where you can set the name of your local fork. You can leave it unchanged, but you may also use a more descriptive name, e.g. 'petscFork', which is used as the example repository name in the following.

Push your Feature to Bitbucket

After creating the fork, all you need to do is push your branch yourname/short-feature-name to the forked repository at Bitbucket. You can also run the first push at an earlier stage already, you don't need to wait for your feature to be complete. To create the remote branch on petscFork, simply issue

  $:petsc> git push -u https://YourUserName@bitbucket.org/YourUserName/petscFork.git yourname/short-feature-name

If you apply any commits to your branch at a later time, simply issue without -u:

  $:petsc> git push https://YourUserName@bitbucket.org/YourUserName/petscFork.git

(If you plan to issue multiple pushes anyway, you may also set up another remote via

  $:petsc> git remote add petscFork https://YourUserName@bitbucket.org/YourUserName/petscFork.git

and push via

  $:petsc> git push -u petscFork yourname/short-feature-name  # First push
  $:petsc> git push petscFork                                 # Subsequent pushes

To send us a pull request, click on the button Pull request near the upper right corner. Select your petscFork-repository with branch yourname/short-feature-name on the left, select the official PETSc repository petsc/petsc with branch master (or maint if it is a bugfix for the latest release) on the right, provide a short description of the new functionality and other changes, and click 'Create pull request'. We will be notified automatically, but you may also send a (probably more verbose) description of the pull request to petsc-dev@mcs.anl.gov.

Updated