Guidelines - ORNL-Fusion/xolotl GitHub Wiki

This page presents different guidelines that Xolotl developers should follow. This is still under development.

• Git
• Versioning
• Contributing
• Deployment and Testing
• Code Style
• Pointers
• Documentation
• Problem or Question

For admins, here is the release checklist.

Git is used to track changes and have different copies of the code at the same time. When committing to the repository, always write a clear comment message. For instance "Writing an example of comment.".

We are using a relaxed GitFlow workflow:

• stable branch is the default branch storing the official release history, each commit to this branch should be tagged with a version number.
• develop branch storing the complete history of the project.
• Feature branches should use the develop branch as their parent branch. When the feature is complete, it should be merged back into develop using a pull request.
• For major changes, a release branch should be used as a buffer between develop and stable. Once ready, release should be merged with both stable and develop.

We use the Apache definition: Versions are denoted using a standard triplet of integers: vMAJOR.MINOR.PATCH. The basic intent is that MAJOR versions are incompatible, large-scale upgrades of the API. MINOR versions retain source and binary compatibility with older minor versions, and changes in the PATCH level are perfectly compatible, forwards and backwards.

MINOR versions are released on a ~6 months basis, associated to a milestone. MAJOR versions are on a case by case basis.

You don't need to have write access to contribute to the development of Xolotl, but you need a Git account. We have decided that people that want to contribute but are not part of the core developers should use pull requests.

Suggested setup for contributing via pull requests:

• Clone the main repo

  git clone https://github.com/ORNL-Fusion/xolotl.git
  

• Create a fork from the main repo (https://github.com/ORNL-Fusion/xolotl) using the "Fork" button at the top right
• Add your fork as a secondary "remote" (assuming you use SSH):

  git remote add <label> [email protected]:<namespace>/xolotl.git
  

  NOTE: It's usually easiest to use your namespace as the label also.

• Check setup with get remote -v (origin should point to the main repo)
• Update both with git remote update or git fetch --all

Process for contributing (given the above setup):

NOTE: Do not commit changes to develop or stable (even in your fork). This way you can keep these branches in-sync with those on the main repo. For example, if origin/develop is ahead of your develop, you can update your fork. On your forked repo page, select the develop branch from the dropdown. Then use the "Sync fork" button to update the corresponding branch in your fork.

• Create a local branch for your changes (based on develop)

  git checkout -b <branch-name>
  

• Commit changes to this branch
• Push these commits to your fork

  git push -u <remote-label> <branch-name>
  

• On GitHub, create a pull request from your branch to the develop branch of ORNL-Fusion/xolotl (not stable)
• Your changes will be reviewed and merged

NOTE: You can continue to push commits to this branch and the PR will automatically update with those changes. If you intend to do this, it's probably best to convert the PR to a draft and add "WIP: " to the PR title until you decide it's ready to be reviewed.

Xolotl development is done through Continuous Integration and Test Driven Development. This means that Xolotl has a lot of tests and it is expected that for every piece of code being committed there will be some sort of test or test update associated with it. Boost Unit Tests are used, if Boost is not present on the machine where Xolotl is installed the tests won't run. See the Build Configuration page for more information on how to get Boost.

The code can be auto-formatted with ClangFormat by running the following command from the Xolotl source directory:

find . -iname *.h -o -iname *.tpp -o -iname *.cpp | xargs clang-format -i

About the naming convention, the names should be as descriptive as possible. Depending on what is being named there are some rules to follow:

• class: noun starting with a upper case letter (example: InterstitialCluster)
• method: verb starting with a lower case letter (example: createReactionConnectivity)
• attribute: noun starting with a lower case letter (example: reactionRadius)

Underscores are mainly avoided, as well as the use of other special characters.

When including header files, the use of <> is preferred to "", meaning the corresponding CMakeLists must be updated.

The strategy in Xolotl is to use both shared pointers and raw pointers for optimization reasons. Smart pointers are excellent at managing memory, but they are expensive because their reference counting must be atomic. Raw pointers are fast, but should no longer (in C++11) be used directly in the creation and deletion of objects because they can be lost, corrupted or directly and unceremoniously deleted. The rule for Xolotl is that smart pointers should be used if a client class is going to be responsible for modifying the existence of an object (create it, delete it, reallocate it, etc.) or needs to know when such an event happens. Otherwise, raw pointers should be used. This is consistent with guidance from the broader C++11 community.

We use JavaDoc style. Anything in the code that is not explicit should be documented.

Doxygen html documentation can be generated from the $HOME/xolotl-build folder by running:

make xolotlDocs

Then the $HOME/xolotl-build/doc/html/index.html file can be opened with your favorite web browser.

This wiki must be well documented too, sometimes it only means copying and pasting the documentation from the code to here, so it is not such a humongous task. Redundant documentation is better than no documentation.

You can either create an issue on the website or send an email to our mailing list: [email protected].