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.
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
## Setup
To setup your local repository for development:
To setup your local repository for development:
1. Fork the main repository on GitHub:
1. Fork the main repository on GitHub:
...
@@ -49,10 +49,10 @@ Setting up git hooks...
...
@@ -49,10 +49,10 @@ Setting up git hooks...
$
$
```
```
### Making a change and submitting a pull request
## 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.
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
### Create the topic branch
1. Make sure you are starting from a current master:
1. Make sure you are starting from a current master:
```
```
...
@@ -79,7 +79,7 @@ Branch <your-topic-branch-name> set up to track remote branch <your-topic-branch
...
@@ -79,7 +79,7 @@ Branch <your-topic-branch-name> set up to track remote branch <your-topic-branch
$
$
```
```
##### Do I need to merge master into my branch first?
#### 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):
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 fetch --all -p
...
@@ -95,7 +95,7 @@ $ git merge upstream/master
...
@@ -95,7 +95,7 @@ $ git merge upstream/master
$ git push -f
$ git push -f
```
```
#### Submit a pull request
### Submit a pull request
1. Log in to your GitHub fork.
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.
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.
3. Fill in the appropriate information for the name of the branch and a brief summary of the changes it contains.
...
@@ -104,14 +104,17 @@ $ git push -f
...
@@ -104,14 +104,17 @@ $ git push -f
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.
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.
### Code formatting and style
## Code formatting and style
ADIOS uses the clang-format tool to automatically enforce source code style and formatting rules. There are various ways to integrate the clang-format tool into your IDE / Code Editor depending on if you use Emacs, Vim, Eclipse, KDevelop, Microsoft Visual Studio, etc. that are a bit outside the scope of this document but a quick google search for "integrate <insert-editor-here> clang-format" should point you in the right direction. However, you can always reformat the code manually by running:
ADIOS uses the clang-format tool to automatically enforce source code style and formatting rules. There are various ways to integrate the clang-format tool into your IDE / Code Editor depending on if you use Emacs, Vim, Eclipse, KDevelop, Microsoft Visual Studio, etc. that are a bit outside the scope of this document but a quick google search for "integrate <insert-editor-here> clang-format" should point you in the right direction. However, you can always reformat the code manually by running:
```
```
clang-format -i SourceFile.cpp SourceFile.h
clang-format -i SourceFile.cpp SourceFile.h
```
```
That will apply the formatting rules used by the ADIOS project.
That will apply the formatting rules used by the ADIOS project.
While some of the formatting rules are fairly detailed, the main points are:
1. Lines no longer than 80 characters.
1. Lines no longer than 80 characters.
1. Always use braces { and }, even for 1 line if blocks.
1. Always use braces { and }, even for 1 line if blocks.
1. Use 4 spaces for indentation.
1. Use 4 spaces for indentation.
There are more formatting rules but these three should at least get you close and prevent any drastic re-writes from the re-formatting tools. More details can be found by looking at the .clang-format config file n the root of the repository and by looking at the clang-format documentation http://releases.llvm.org/3.8.0/tools/clang/docs/ClangFormatStyleOptions.html. While the formatting rules are a bit more involved, the main points are:
There are more formatting rules but these three should at least get you close and prevent any drastic re-writes from the re-formatting tools. More details can be found by looking at the .clang-format config file in the root of the repository and by looking at the clang-format documentation http://releases.llvm.org/3.8.0/tools/clang/docs/ClangFormatStyleOptions.html.
