Skip to content

Guidelines

Jump to bottom
Sophie Blondel edited this page Jun 17, 2024 · 6 revisions

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

Git

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.

Versioning

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.

Contributing

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. The process is the following:

  • fork the repository from the main code page, there is an icon located in the top right corner when you are in the Code tab
  • clone your own forked repository and apply the changes you want using git add, git commit, git push, etc.
  • when you are ready to merge your changes with the main repository, create a pull request
  • the request will be reviewed and accepted/commented

Deployment and Testing

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.

Code Style

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.

Pointers

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.

Documentation

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.

Problem or Question

You can either create an issue on the website or send an email to our mailing list: xolotl-psi-development@lists.sourceforge.net.

Clone this wiki locally