Contributing.md

Contributor's Guide

This guide will walk you through how to submit changes to ADIOS 2.0 and interact with the project as a developer. Information found on ADIOS 2.0 wiki: https://github.com/ornladios/ADIOS2/wiki under the Contributing to ADIOS section.

Table of Contents

• Contributor's Guide
• Table of Contents
  • Workflow
  • Setup
  • Making a change and submitting a pull request
    • Create the topic branch
      • Do I need to merge master into my branch first?
    • Submit a pull request
  • Template implementation separation
    • Example
      • Before separation of public and private template implementation
        • Foo.h
      • After separation of public and private template implementation
        • Foo.h
        • Foo.inl
        • Foo.tcc
        • Foo.cpp
  • Code formatting and style

Workflow

ADIOS uses the GitHub fork-and-branch model. In this, the project "lives" in it's main repository located at https://github.com/ornladios/adios2.git, while each individual developer has their own copy of the repo to work in. Changes are then submitted to the main repository via pull-requests made with branches from your fork.

Setup

To setup your local repository for development:

1. Fork the main repository on GitHub:
   1. Navigate to https://github.com/ornladios/adios2 in your browser.
   2. Click the [Fork] button in the upper right-hand side of the page.
2. Clone the upstream repository to your local machine:

$ mkdir adios
$ cd adios
$ git clone https://github.com/ornladios/adios2.git source
Cloning into 'source'...
remote: Counting objects: 4632, done.
remote: Compressing objects: 100% (80/80), done.
remote: Total 4632 (delta 33), reused 0 (delta 0), pack-reused 4549
Receiving objects: 100% (4632/4632), 1.23 MiB | 224.00 KiB/s, done.
Resolving deltas: 100% (2738/2738), done.
Checking connectivity... done.
$

3. Run the scripts/development/setup.sh script. The script will configure an upstream remote and link your local master branch to the upstream.

$ cd source/
$ ./scripts/developer/setup.sh 
Enter your GitHub username: chuckatkins
Setup SSH push access? [(y)/n] y
Re-configuring local master branch to use upstream
Fetching origin
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 6 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (6/6), done.
From https://github.com/chuckatkins/adios2
Fetching upstream
From https://github.com/ornladios/adios2
 * [new branch]      master     -> upstream/master
 * [new branch]      dashboard  -> upstream/dashboard
 * [new branch]      hooks      -> upstream/hooks
Setting up git aliases...
Setting up git hooks...
$

Making a change and submitting a pull request

At this point you are ready to get to work. The first thing to do is to create a branch. ADIOS uses a "branchy" workflow where all changes are committed through self-contained "topic branches". This helps ensure a clean traceable git history and reduce conflicts.

Create the 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: