Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
182 lines (130 loc) · 5.72 KB

CONTRIBUTING.md

File metadata and controls

182 lines (130 loc) · 5.72 KB
Raw

Contributing to Arcane Framework

Thank you for contributing to Arcane Framework. This guide describes the workflow and repository conventions used for contributions.

Before you start

Read the project README and the relevant component documentation before making a change. Arcane Framework is a monorepo; keep a contribution focused on the component it changes (arccore, arcane, alien, arccon, or axlstar).

Clone the repository with its submodules:

git clone --recurse-submodules https://github.com/arcaneframework/framework.git

If the repository was cloned without submodules, initialise them before configuring CMake:

git submodule update --init --recursive

For prerequisites and platform-specific installation instructions, see the build and installation guide.

Build and test your change

Use an out-of-source build directory. A regular Arcane build can be configured with the supplied preset:

cmake --preset Arcane
cmake --build out/build/Arcane

Alternatively, configure a dedicated build directory explicitly. Select only the components needed for the change when that makes the feedback loop faster:

cmake -S . -B build -DARCANEFRAMEWORK_BUILD_COMPONENTS=Arcane
cmake --build build

Run the relevant tests before opening or updating a pull request:

The commands below use the explicit build directory shown above. If you use the Arcane preset, replace build with out/build/Arcane.

ctest --test-dir build --output-on-failure

Use a targeted invocation when appropriate:

ctest --test-dir build --output-on-failure -R <test-name>

Some tests require MPI. When running as root in a container or CI environment, Open MPI may require the following variables:

export OMPI_ALLOW_RUN_AS_ROOT=1
export OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1

Code and file conventions

Follow .editorconfig. In particular, C++, C#, CMake, and CMakeLists.txt files use two spaces for indentation and no trailing whitespace.

Format every modified source file with clang-format before pushing. Use the _clang-format file from the relevant arcane/ or arccore/ directory.

New or edited .cc and .h files are checked in CI for the project header, copyright notice, and UTF-8 with BOM encoding. Start from a nearby maintained source file in the same component so that these conventions are preserved.

Keep public API changes deliberate. In Arcane, the stable public API is limited to core/, materials/, utils/, launcher/, accelerator/, cartesianmesh/, and hdf5/; other arcane/ directories are internal.

Branch names

Create a branch using this pattern:

dev/<initials>-<short-description>

For example:

dev/ah-alien-doxygen

Commit messages

Keep each commit focused and as small as practical. A commit must affect only one framework part (for example, Arcane or Arccore) and leave the framework buildable.

Use the following subject format:

[<part>,<subdirectory>] Short imperative summary

For example:

[arcane,cartesianmesh] Add InPatch/Overlap flags on nodes and faces

When a commit affects several subdirectories of the same part, list them in the scope:

[<part>,<subdirectory-1>+<subdirectory-2>] Short imperative summary

When work is delivered as a small, ordered commit series, number the commits clearly:

[<part>,<subdirectory>] [1/2] First change
[<part>,<subdirectory>] [2/2] Follow-up change

Temporary work-in-progress commits are acceptable locally. Mark them as [Draft], then amend or squash them before the pull request is merged.

Commit signing will become mandatory at the end of 2026. See GitHub's documentation on commit signature verification to prepare your environment.

License and contributions

Arcane Framework is distributed under the Apache License, Version 2.0. By submitting a contribution for inclusion in the project, you confirm that you have the right to submit it and, unless you explicitly state otherwise, submit it under that license, as provided by section 5 of the Apache License, Version 2.0.

All contributors must sign the project's Contributor License Agreement (CLA) through CLA Assistant before their pull request can be merged. The CLA grants the permissions needed to maintain and, if necessary, change the project's license while contributors retain copyright in their work.

CLA Assistant checks every pull request. Sign the CLA when prompted; a valid signature is reused for later pull requests unless the CLA changes. Do not submit a contribution subject to terms that are incompatible with the project license.

Pull requests

Before requesting review:

  • Assign the pull request to yourself.
  • Choose every label that describes the change.
  • Ensure the title clearly describes the result; add a short description when the title alone is insufficient.
  • Sign the Contributor License Agreement when requested by CLA Assistant.
  • Build the affected configuration and run relevant tests locally.
  • Keep the pull request focused. Explain compatibility implications, generated files, or intentionally untested paths in its description.

Keep the branch up to date with main by rebasing; do not merge main into the contribution branch:

git fetch origin
git rebase origin/main

Resolve conflicts and rerun the appropriate build and tests after the rebase. Once approved and checks pass, merge the pull request into main with a merge commit; do not use squash or rebase merging.