Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
164 lines (128 loc) · 8.54 KB

CONTRIBUTING.md

File metadata and controls

164 lines (128 loc) · 8.54 KB

Code formatting

Source code should follow the formatting conventions established in the project. There are several software configurations to help developers format their code:

  1. .editorconfig specifies basic formatting elements, such as character set and indentation width. Many text editors and IDEs provide built-in support or a plugin for editorconfig, see https://editorconfig.org/ for details.
  2. The .clang-format file contains detailed specification for C++ source code formatting. Automatic formatting may be applied with clang-format version 13 or later. Use the run-clang-format.py script for parallel processing and correct formatting of CUDA kernel launches and OpenMP pragmas. The script is also run in a continuous integration job on Gitlab to give developers hints about what should be reformatted.
  3. Source files in the src/TNL/ directory should include a copyright header at the top. The update-copyright-headers.py script can be used to generate or update copyright headers in source files.

When you are unsure or if something is not specified in the aforementioned configuration, rely on mirroring the formatting style of existing code.

Note: Code formatting changes should be applied before making a commit, i.e., all commits should be already formatted correctly. Ideally, there should be no separate commits to fix formatting issues. When working on a feature branch, you can squash separate commits fixing style issues into previous commits which introduced the problem (see below on how to use the interactive rebase).

Code linting

The continuous integration on Gitlab features a code linting job using clang-tidy to help developers diagnose and fix common programming errors. The configuration is provided in the .clang-tidy file. Various editors and IDEs provide integrations either directly for clang-tidy or for clangd (which integrates clang-tidy). This way, you can get full linting directly in your editor without having to rely on the continuous integration.

How to configure git

It is important to configure your git username and email address, since every git commit will use this information to identify you as the author:

git config --global user.name "John Doe"
git config --global user.email "john.doe@example.com"

In the TNL project, this username should be your real name (given name and family name) and the email address should be the email address used in the Gitlab profile. You should use the same configuration on all computers where you make commits. If you have made some commits with a different email address in the past, you can also add secondary email addresses to the Gitlab profile.

How to write good commit messages

Begin with a short summary line, a.k.a. message subject:

  • Use up to 50 characters; this is the git official preference.
  • Finish without a sentence-ending period.

Continue with a longer description, a.k.a. message body:

  • Add a blank line after the summary line, then write as much as you want.
  • Use up to 72 characters per line for typical text for word wrap.
  • Use as many characters as needed for atypical text, such as URLs, terminal output, formatted messages, etc.
  • Include any kind of notes, links, examples, etc.

See 5 Useful Tips For A Better Commit Message and How to Write a Git Commit Message for examples and reasoning.

How to split commits

Extensive changes should be split into multiple commits so that only related changes are made in each commit. All changes made in a commit should be described in its commit message. If describing all changes would not result in a good commit message, you should probably make multiple separate commits.

Multiple small commits are better than one big commit, because later they can be easily squashed together, whereas splitting a big commit into logical parts is significantly more difficult.

Tip: Use git add -p to stage only part of your working tree for the next commit. See git add -p: The most powerful git feature you're not using yet.

Rebase-based workflow

The development of new features should follow the rebase-based workflow:

  • Create a new feature branch based on the main branch (develop).
  • Make commits with your work in the feature branch.
  • When there are other new commits in the develop branch, you should do a rebase to rewind your commits on top of the current develop branch.
    • If there are conflicts, you will need to resolve them manually. Hence, it is a good practice to rebase as often as possible (generally as soon as the changes appear in the develop branch) and to split commits into logical parts.
  • When your work is ready for review, you can open a merge request.
    • If the branch is not ready for merge yet, prepend [WIP] to the merge request title to indicate work in progress and to prevent a premature merge.
    • This is also a good time to squash small commits (e.g. typos, forgotten changes or trivial corrections) with relevant bigger commits to make the review easier.
  • When your work in the feature branch is finished, you should also do an interactive rebase and squash small commits (notably when fixing typos or compilation problems), reword commit messages (check all typos) and overall make the history nice.
  • When reviewed, the feature branch can be merged into the develop branch.

The main advantages of this workflow are linear history, clear commits and reduction of merge conflicts. See A rebase-based workflow and Why is rebase-then-merge better than just merge (complement) for reference.

AI-assisted contributions policy

  1. You MAY use AI assistance for contributing to TNL, as long as you follow the principles below.

  2. Accountability: You MUST take responsibility for your contribution. Contributing to TNL means vouching for the correctness, license compliance, and quality of your submission. The contributor is always the author and is fully accountable for the entirety of contributions, whether human-written or AI-assisted.

  3. Transparency: You MUST disclose the use of AI tools when a significant part of the contribution is generated without substantial human modification. You SHOULD disclose other uses where it might be useful for project visibility.

    Routine use of assistive tools for correcting grammar, spelling, or clarifying language does not require disclosure.

    Disclosure method: For git-tracked contributions, use the Assisted-by: trailer in commit messages. For example:

    Assisted-by: Claude Opus 4.6 (Anthropic)
Assisted-by: GLM-5 via Opencode

    For other contributions such as comments or replies, include a note indicating AI assistance.

  4. Community interaction: AI tools MAY assist human reviewers by providing analysis and suggestions. Reviewers MUST NOT use AI as the sole or final arbiter on a contribution. The final accountability for accepting or rejecting a contribution, even if implemented by an automated system, always rests with the human contributor who authorizes the action.

  5. Large-scale initiatives: You MUST NOT use AI assistants to initiate contributions that may inflict significant burden on human contributors or lead to exponential growth without prior discussion with project maintainers.

The key words “MAY”, “MUST”, “MUST NOT”, and “SHOULD” in this section are to be interpreted as described in RFC 2119.