Submitting Changes

ADIOS2 uses a "branchy" workflow where all changes are committed through self-contained "topic branches" via GitHub pull requests (PR). Submitting changes is a four step process:

1. Create a topic branch with git checkout
2. Make changes to the code, commit and push to your fork
3. Submit a pull request (PR) on GitHub
4. Make changes until all tests are verified

Create a topic branch

1. Make sure you are starting from a current master:

   $ git checkout master
   $ git pull
   

2. Create a branch for your change:

   $ git checkout -b <your-topic-branch-name>
   

3. Make your changes and commits to the branch.
4. Push the branch to your fork:

   $ git push -u origin HEAD
   Counting objects: 189, done.
   Delta compression using up to 8 threads.
   Compressing objects: 100% (134/134), done.
   Writing objects: 100% (189/189), 70.30 KiB | 0 bytes/s, done.
   Total 189 (delta 128), reused 102 (delta 44)
   remote: Resolving deltas: 100% (128/128), completed with 82 local objects.
   To git@github.com:<your-GitHub-username-here>/adios2.git
   * [new branch]      HEAD -> <your-topic-branch-name>
   Branch <your-topic-branch-name> set up to track remote branch <your-topic-branch-name> from origin.
   $
   

Do I need to merge master into my branch first?

Not usually. The only time to do that is to resolve conflicts. You're pull request will be automatically rejected if merge-conflicts exist, in which case you can then resolve them by either re-basing your branch the current master (preferable):

$ git fetch --all -p
...
$ git rebase upstream/master
$ git push -f

or if necessary or re-basing is not a viable option then you can always fall back to merging in master but it should be generally discouraged as it tends to make the git history difficult to follow:

$ git fetch --all -p
...
$ git merge upstream/master
$ git push -f

Submit a pull request

1. Log in to your GitHub fork.
2. You should see a message at the top that informs you of your recently pushed branch, something like: <your-topic-branch-name> (2 minutes ago). On the right side, select the [Compare & pull request] button.
3. Fill in the appropriate information for the name of the branch and a brief summary of the changes it contains.
   • The default configuration will be for the topic branch to be merged into the upstream's master branch. You can change this if you want to submit to a different branch.
   • If you are not done with your topic branch, start your PR name with WIP: (after work in progress). Example: WIP: Adding bzip2 compression
4. Click [Create pull request].

You have now created a pull request (PR) that is pending several status checks before it can be merged. Currently, the only check being performed is for source code formatting and style. In the future, however, the will be a more in depth continuous integration system tied to the pull requests that tests for build and test failures every time a PR is submitted or updated. Once the status checks pass, the PR will be eligible for merging by one of the project maintainers.