Guidelines for Contributors

Boost.uBlas is a free and open-source library that is part of the Boost C++ libraries. We welcome anyone who wants to contribute and enhance uBlas by for instance adding new features, fixing software bugs or enhance our software and infrastructure in general. Boost.uBlas is a more than a decade old library maintained by several developers with help from a couple of dozens contributors. It is important to maintain consistent design, look and feel. Thus, below a few basic guidelines are listed and we hope that you follow them.

Table of Content

• Prerequisites
• Copyrights and Licensing
• Git
• Pull Requests
• Guidelines
• Next Steps

Prerequisites

Contributing to Boost.uBlas can be quite challenging which is why it is very important to first read and make yourself acquainted with Boost.uBlas. We assume that you

• you are an experienced C++ programmer who can apply many of the C++17 and C++20 features
• are able to apply and understand most of the C++ core guidelines
• have experience with git and understand collaborative workflows
• communicate and engage with everyone in the community to behave as describe in our code of conduct
• you will read this document until the end and apply those rules

We encourage you to

• read the opensource guidelines if you are new to open source contribution
• look at the Boost Getting Started chapters
• make yourself familiar with Boost specific design methods
• skim through Boost's requirement and the general guidelines page
• understand the Boost.Build system by skimming through its documentation

If you have never used Boost.uBlas, you should

• clone and install Boost.uBlas according to the installation documentation
• build and play around with already existing examples
• build and execute tests

Make sure you understand how Boost.uBlas contributors communicate:

• software versioning and feature creation happens in the code and pull requests tabs
• existing and future projects are placed inside projects tab
• issues and bugs are placed inside the issues tab
• discussions, questions, proposals, etc. usually happen in the discussions tab
• announcements and short questions are placed and raised in the gitter channel

Developing

Strive for writing idiomatic C++11, clean and elegant code.

Some Boost.uBLAS source code does not necessary represent clean and elegant code to look up to. The library has recently entered the transition to C++20 using tensor as its base template. Major refactoring overhaul is ongoing

Maintain structure your source code files according to the following guidelines:

• Name files in meaningful way.
• Put copyright and license information in every file
• If your changes meet a certain threshold of originality add yourself to the copyright notice.
• Do not put any additional authorship or file comments (eg. no \file for Doxygen), revision information, etc.
• Do not delete copyright information
• Make sure each header is self-contained, i.e. that they include all headers they need.
• All public headers should be placed in boost/numeric/ublas/ or boost/numeric/ublas/<component>/.
• All non-public headers should be placed boost/numeric/ublas/detail or boost/numeric/ublas/component>/detail.
• All public definitions should reside in scope of namespace boost { namespace numeric { namespace ublas {...}}}.
• All non-public definitions should reside in scope of namespace boost { namespace numeric { namespace ublas { namespace detail {...}}}}.
• Do not increases the indentation level within namespace.

Features and Bugfixes

Among many existing workflows, we have decided to mainly work according to the gitflow. It is based on the Feature Branch Workflow in which all feature development takes place in dedicated branches instead of the main or master branch. Boostorg/ublas consists of at least the master and develop branch. The master branch stores the official release history, and the develop branch serves as an integration branch for features. Features should be named feature/<feature-name>, while bug fixes should be named bugfix/<bugfix-name>. A release branch does not exist. This encapsulation makes it easy for multiple developers to work on a particular feature without disturbing the main codebase on master. Minor adjustments are allowed on develop when those changes do not interfere with the flow of other contributors. Following the feature-branch workflow, all Boost.uBLAS contributions should be created by branching off the develop branch of boostorg/ublas.

Next, checkout the develop branch and bring it up to date

git checkout develop
git branch -vv
git pull origin develop

Assuming that you do not have write-access, fork Boost.uBlas repository on GitHub, follow the forking guide to get personal copy of boostorg/ublas repository, see also fork. From there you will be able to submit new contributions as pull requests.

Next, add fork as a git remote:

cd libs/numeric/ublas
git remote add fork https://github.com/somename/ublas.git
git fetch fork

Next, checkout develop locally and create a branch e.g. feature from develop that tracks forked fork/develop: Note that you should give feature a more meaningful name.

git checkout develop
git checkout -B feature --track fork/develop

Now, you are set to to develop a new feature for Boost.uBlas. You git add and git commit your changes. We want our git commit messages to be human and machine readable as described in conventional commits and angular commit message guidelines.

Commit Message Format Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and the scope of the header is optional. Any line of the commit message should not be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Test Features and Bug-Fixes

We heavily encourage you to develop your features and bug-fixes in a test-driven manner or at least test your code. If you provide a new feature make sure that you are creating unit-tests (upfront) that thoroughly check the functionality with different tensor types and instances. You can copy and modify unit-tests that reside inside test folder.

cd libs/numeric/ublas
../../../b2 -j8 release toolset=clang cxxflags="-O3" test/tensor

We also recommend to run clang-tidy tests that help to find many bugs in the code.

Pull Requests

Merging features and bug fixes into develop is performed with a pull-request, see also pull requests. IMPORTANT: Pull Requests must come from a branch based on develop, and never on master. Once it's finished, you can submit it as pull request for review:

cd libs/numeric/ublas
git checkout feature
git push

Finally, sign in to your GitHub account and create a pull request.

Your pull request will be automatically built and tests will run on Github Actions. Please, keep an eye on those CI builds and correct any problems detected in your contribution by updating your pull request. In simplest (and recommended) case , your the pull request you submitted earlier has a single commit, so you can simply update the existing commit with any modifications required to fix failing CI builds or requested by reviewers.

First, it is a good idea to synchronize your topic branch with the latest changes in the upstream develop branch:

cd libs/numeric/ublas
git checkout develop
git pull origin develop
git checkout feature
git rebase develop

Next, make your edits.

Finally, git commit --amend the single-commit in your topic branch and update the pull request:

cd libs/numeric/ublas
git checkout feature
git add -A
git commit --amend
git push --force

WARNING: Ensure your pull request has a single commit, otherwise the force push can corrupt your pull request.

If you wish to update pull request adding a new commit, then create new commit and issue regular push:

git checkout feature
git commit -m "Fix variable name"
git push feature

• DO submit all major changes to code via pull requests (PRs) rather than through a direct commit. PRs will be CI-checked first, then reviewed and potentially merged by the repo maintainers after a peer review that includes at least one maintainer. Contributors with commit access may submit trivial patches or changes to the project infrastructure configuration via direct commits (CAUTION!)
• DO NOT mix independent, unrelated changes in one PR. Separate unrelated fixes into separate PRs, especially if they are in different components (e.g. core headers versus extensions). Separate real product/test code changes from larger code formatting/dead code removal changes, unless the former are extensive enough to justify such refactoring, then also mention it.
• DO start PR subject with "WIP:" tag if you submit it as "work in progress". A PR should preferably be submitted when it is considered ready for review and subsequent merging by the contributor. Otherwise, clearly indicate it is not yet ready. The "WIP:" tag will also help maintainers to label your PR with [status/work-in-progress].
• DO give PRs short-but-descriptive names (e.g. "Adding test for algorithm xyz", not "Fix #1234").
• DO [refer] to any relevant issues, and include the [keywords] that automatically close issues when the PR is merged.
• DO [mention] any users that should know about and/or review the change.
• DO ensure each commit successfully builds. The entire PR must pass all tests in the Continuous Integration (CI) system before it'll be merged.
• DO address PR feedback in an additional commit(s) rather than amending the existing commits, and only rebase/squash them when necessary. This makes it easier for reviewers to track changes.
• DO assume that the [Squash and Merge] will be used to merge your commit unless you request otherwise in the PR.
• DO NOT fix merge conflicts using a merge commit. Prefer git rebase.

Merging Pull Requests (for maintainers with write access)

• DO use [Squash and Merge] by default for individual contributions unless requested by the PR author. Do so, even if the PR contains only one commit. It creates a simpler history than [Create a Merge Commit].
  Reasons that PR authors may request the true merge recording a merge commit may include (but are not limited to):

  • The change is easier to understand as a series of focused commits.
    Each commit in the series must be buildable so as not to break git bisect.
  • Contributor is using an e-mail address other than the primary GitHub address and wants that preserved in the history.
    Contributor must be willing to squash the commits manually before acceptance.

Next Steps

A good way to start contributing is

• to pick one issue and try to solve it or
• to contribute to one of the existing projects
• to discuss and present your solution on the discussion tab and announce it the Boost.ublas gitter channel