bitpitStyleGuide.hpp

 
\endverbatim
The doxygen comment block of a class should include a general description of
the class and a list of its features and possible limitations.
 
A doxygen comment block should be added for every method of a class (both
public and private methos should be commented), this comment block should
contain a general description of the method and a description of all the
arguments and the return value of the method. For instance:
\verbatim
\endverbatim
 
To document the members of a file, struct, union, class, or enum, it is sometimes
desired to place the documentation block after the member instead of before.
For this purpose an additional < marker is required in the comment block.
Note that this also works for the parameters of a function. For instance:
\verbatim
    int var; 
\endverbatim
To simplify the documentation of class members, define just one member per
line (no commas for multiple members declarations).
 
Doxygen commands should start with a backslash (\\).
 
As a rule of thumb, the code should run through doxygen without generating any
warnings; in fact, doxygen is sometimes helpful at pointing out inconsistencies
in your class declaration.
 
\subsection automatic_formatting Automatic code formatting
 
<B>%bitpit</B> provides a .clang-format file that can be used by clang-format
to automatically format the code. Code formatting can be enforced manually by
calling clang-format directly or automatically through the the CMake targets
defined by <B>%bitpit</B>. Each <B>%bitpit</B> module provides a CMake target
called clang-format-<MODULE_NAME> that allows to format all the code of the
module. There is also a Git pre-commit hook which uses the "clang-format git
hooks" tool to ensure the changes are properly formatted.
 
\section git Git Repository Practices
As most of our code repositories uses git as the revision control system, it is important to decide on a workflow that can be followed by the individual developer. The way that any individual developer interact with the upstream git repository can have an important impact on other developers and the ability to identify and manage individual changes.  This set of guidelines and practices attempts to establish some standards for how developers will interact with the upstream git repository.
 
\subsection commits Making Repository Commits
As a general rule, developers should update frequently, and commit changes often.  However, the repository should always remain
in a state where the code can be compiled.  Most of the time, the code should also successfully execute "make check" run from the
top-level directory.  If you commit code that violates this principal, it should be your first priority to return the repository
code to a compilable state, and your second priority to make sure "make check" runs without errors.
Although it would be possible and many software projects do it, we prefer not to force successful execution of the test suite
before every commit.  Developers should make every effort to avoid having to impose this constraint, by running a make check
before every commit.
 
Commits to the repository should also come with a non-trivial and useful log message.
 
\subsection outside-master Working Outside the Master Branch
A critical concept is that all changes shall be developed outside of the master<sup>1</sup> branch.  Whether they are in a different branch of the upstream<sup>2</sup> repository (gitflow) or a branch of an entirely different fork (forking workflow) is secondary.  This is a well-established concept regardless of the workflow being adopted, and allows a number of other benefits as described below.
 
\subsubsection fork Working on a Different Fork
There are a number of benefits of working on a different fork rather than a branch of the upstream repo, although not strictly technical:
- Developers, particularly new developers, are liberated from the constant oversight of others as they explore new code options.  The impact of this may depend on an individual developer’s personality, but for some it creates a refuge where they can be more free and creative.
- Similarly, assuming that all changesets in the upstream repo are communicated to the entire development team, the team is spared a noisy stream of notifications and can focus their attention on the rarer occurrence of a pull request notification.
 
\subsubsection pr All Changes are Committed by Pull Request
Although this can be imposed technically by limiting the authority to alter the upstream repo (as in the forking workflow), a healthy developer community can also simply rely on convention.  The advantage of doing it by convention rather than by restriction is that it is easier to distribute the load of reviewing and accepting changes.
A critical consequence of this decision is that all code is reviewed before it is committed to the upstream master branch.  This has benefits to overall quality in two related ways:
- the code under review will improve due to the review itself, and
- those involved in the review will maintain a broad awareness of the code base resulting in better contributions from them.
 
This practice does, however, place a substantial burden on the developers to perform timely reviews of the pull requested (PR’ed) code.  PR’s that languish without sufficient review have a number of negative consequences:
- they need to be refreshed simply to keep them up-to-date with the possibly advancing upstream/master
- they may delay further development on similar or related features
- they breed frustration in the original developer, undermining the community as a whole.
github provides powerful collaboration tools that greatly facilitate this process.
 
<sup>1</sup> Although a repository may choose a different name for its main development branch, this document will refer to that as the “master” branch.
 
<sup>2</sup> For this discussion, the “upstream” repo will refer to the centralized authoritative repository used to synchronize changes.
 
\subsection git-mechanics Some Git Mechanics to Keep it Clean
Given the above practices, there are some mechanical details that can help ensure that the upstream/master repository is always in a state that facilitates all repository actions and interactions.
 
-# Feature branches being used for development should be kept up-to-date with the upstream/master by rebase only.  When a feature branch is rebased against the upstream/master, all changes in the upstream/master are inserted into the feature branch at a point in its history that is prior to any of the changes of the feature branch.  This can require conflict resultion as the feature branch changes are “replayed” on top of the new upstream/master in its current state.  The primary advantage of this policy is that it keeps all of the feature branch changes contiguous.  If, by contrast, the upstream/master is merged into the feature branch, the recent changes in the upstream/master become woven into the set of changes in the feature branch.  This can make it more difficult to isolate changes later on.
 
    Strict adoption of this practice is important since a single merge into a feature branch that is then merged back into the upstream/master can make it nearly impossible for others to rebase.
 
    A typical workflow with pull-request might look like this, all using the command-line, except for submitting the final pull request.  Note that there is never a merge operation.
    -# synchronize your local `master` branch before anything else
    \code{.sh}
     $ git checkout master
     $ git fetch upstream
     $ git rebase upstream/master
     \endcode
 
    -# now create a new feature branch from master
    \code{.sh}
     $ git checkout -b my_feature_branch master
    \endcode
 
    -# now make changes, editing A.cpp, B.hpp, C.cpp
 
    -# now add/commit your changes to your local feature branch
    \code{.sh}
     $ git add A.cpp B.hpp C.cpp
     $ git commit -m “Make sure you have a good commit message”
    \endcode
    -# push your changes to your feature branch on your fork (often called `origin`)
    \code{.sh}
     $ git push origin my_feature_branch
    \endcode
    -# make more changes, editing B.hpp, D.hpp, E.cpp
 
    -# add/commit your changes to your local feature branch
    \code{.sh}
    $ git add B.hpp D.hpp E.cpp
    $ git commit -m “Be sure you have another good commit message”
    \endcode
    -# push your changes to your freature branch on your fork (often called `origin`)
    \code{.sh}
    $ git push origin my_feature_ranch
    \endcode
    -# When you are ready to submit a pull request, be sure that your feature branch is up-to-date. This first step may seem redundant but is here to be clear which branch we are acting on
    \code{.sh}
    $ git checkout my_feature_branch
    $ git fetch upstream
    $ git rebase upstream/master
    \endcode
      This may generate conflicts that can be addressed at this point.
 
      NOTE: This step can be performed at any time and should be performed as often as practical to reduce the scope of potential conflicts.
 
    -# push your updated feature branch on your fork (often called `origin`)
     \code{.sh}
     $ git push origin my_feature_branch
     \endcode
      This may require the ‘-f’ option to force the push.  (It is frequently necessary to force this push because the act of rebasing will “replay” the commits from the feature branch on top of the master, leading to different commit hashes.  Each of the commits will contain the same actual information, but because it has a different set of hashes, git will think there is an inconsistency and ask you to force the change.)
 
    -# Submit a pull request on github, from your fork to the fathomteam fork.
 
 
-# When ready to be adopted into the upstream/master, feature branches should be combined by merge only.  This adds the changeset to the end of the upstream/master as a set of individual commits but in a contiguous block.
 
   A typical workflow to merge a pull-request might look like this, all using the command-line.
   -# synchronize your local `master` branch before anything else (just because it’s never a bad idea!)
   \code{.sh}
   $ git checkout master
   $ git fetch upstream
   $ git rebase upstream/master
   \endcode
   -# add a remote for the user with the pull-request, perhaps the user is ‘other_user’
   \code{.sh}
   $ git remote add other_user \
         git@bitbucket.org:other_user/moab.git
   \endcode
   -# fetch the other users repo
   \code{.sh}
   $ git fetch other_user
   \endcode
   -# check out their feature branch
   \code{.sh}
   $ git checkout -b pr_feature_branch \
       other_user/feature_branch
   \endcode
   -# confirm that it is up-to-date with the master. This first step may seem redundant but is here to be clear which branch we are acting on
   \code{.sh}
   $ git checkout pr_feature_branch
   $ git fetch upstream
   $ git rebase upstream/master
   \endcode
   This may generate conflicts that can be addressed at this point.  You may want to request the original author (other_user) take care of these.
   -# once confirmed that it’s up-to-date with master, review this branch including:
      -reading the code
      -building the code
      -running tests
   -# once satisfied that the code meets the necessary standards and that all required/requested changes are fully incorporated into other_users’s feature branch, merge it into master
    \code{.sh}
    $ git checkout master
    \endcode
    The next two steps may seem redundant but provide some QA
    \code{.sh}
    $ git fetch upstream
    $ git rebase upstream/master
    $ git merge other_user/feature_branch
    \endcode
   -# push those changes into the master branch on bitbucket
    \code{.sh}
    $ git push upstream/master
    \endcode
 
-# When a pull request is open for review, any changes to the feature branch will automatically update the pull request.  This is the appropriate way for a developer to respond to requests for changes that occur through the PR process.
 
 
-# If a developer has ongoing work that is based on a feature branch that is under consideration in an open PR, a new feature branch (B) should be created that is based on the previous feature branch (A).  Moreover, as changes are made to the original feature branch (A) due to the review process, the new feature branch (B) should be kept up-to-date by rebase against feature branch (A).  This keeps all subsequent changes of (B) downstream from the changes in (A).  Once feature branch (A) has been adopted into the upstream/master, the new feature branch (B) can start being rebased against the upstream/master instead.
 
 
-# When a repo is forked, its branches are not automatically synchronized with the corresponding branches on the upstream repo.  This requires a manual process of synchronization via a local clone.  Assuming that the local repo’s branch has the same name as the upstream branch (\<branch\>), and that the fork is known as “origin”:
    \code{.sh}
     $ git fetch upstream
     $ git checkout <branch>
     $ git rebase upstream/<branch>
     $ git push origin <branch>
    \endcode
The decision of which branches to keep up-to-date is up to the developers.  Developers may choose to delete some branches from their own fork to avoid (a) the need to update it and (b) accidentally assuming that it is up-to-date.
 
 
-# When rebasing, it is not uncommon to encounter conflicts.  This will interrupt the rebasing process, and each conflicted file will contain conflict blocks.  You will be offered three choices:
 - manually resolve the conflicts, add the resolved files with git add,  and then git rebase --continue (do not commit the resolved files!)
 - abort the rebasing process entirely with git rebase --abort
 - skip the commit that causes the conflict, assuming that you are sure that this is the right thing to do, with git rebase --skip
 
 
-# github offers a number of buttons/tools to manage changes between branches and forks.  Some of these operate in ways that are contrary to the practices recommended here, and others are consistent with these practices.  In general, it is best to know how to do all of those operations with the command-line instead of relying on github, as it gives you full control over important details.
 
 
-# During code development, it might be necessary to work on the same branch on different machines. The workflow to update the local branch is to first fetch the remote changes and then perform a hard reset.
     \code{.sh}
     $ git fetch origin
     $ git reset --hard origin/branch_name
     \endcode
One should be careful with the branch name as a hard reset would overwrite all changes in the working directory.
 
 
Top: \ref styleguide
 
*/