Contributing to airGRiwrm • airGRiwrm

📌 Before you start

Please open an issue to discuss any new feature or bug fix before starting development. This allows for discussion and coordination:
- if you can access the INRAE Forge, open it on GitLab, the source of truth for the development;
- otherwise, open it on the GitHub mirror — the maintainers track issues opened there.
Check existing issues and merge requests to avoid duplicating work.

💡 How to contribute

Open an issue (on GitLab if you have access to the INRAE Forge, otherwise on the GitHub mirror) describing the bug, enhancement, or new feature. Please provide enough context and, if applicable, a reproducible example.
Once the issue is triaged and assigned to you (or you are the assignee), create a Merge Request (MR) and a new branch from the issue page and assign a reviewer.
Make your changes following the tidyverse style guide. Ensure you:
- add or update documentation using roxygen2
- add or update tests in tests/testthat/
- run devtools::check() and fix any issues
Commit and push your changes to your branch:
- try to keep each commit as consistent as possible to a simple task (feature, test, documentation, …)
- comment your commits using the Conventional Commit specification
When the work is done, trigger a review:
- remove the “Draft” state on your MR and eventually contact the reviewer to trigger the review
- respond to code reviews and adjust your MR as needed until it is approved and merged.

🌿 Branches and git conventions

dev is the development branch; all feature branches are merged into it.
master holds the released versions only (a master state equals the last CRAN release).
The maintainer is the sole merge decision-maker for master: MRs toward master are merged by the maintainer.
Direct commits on dev that do not change source code (docs-only or tests-only commits) carry a [skip ci] tag in the commit subject so that the CI dev-version auto-bump is not triggered.
The dev version number (X.Y.Z.90xx) is bumped automatically by the CI on every source-code commit to dev (a commit + tag vX.Y.Z.90xx are created by the pipeline); it is never set by hand.
Version tags created on GitLab are pushed to the GitHub mirror automatically by the github_tags CI job.

🎨 Coding style

Note on naming: there is no strict rule — the functions related to airGR follow the PascalCase convention of the airGR package, the other functions use camelCase; match the style of the existing code.

You can use the air package to format your code.

🧪 Testing

All new features and bug fixes should include unit tests using the testthat framework.

Add tests in tests/testthat/, ideally in files named after the function or feature being tested.

📚 Documentation

Use roxygen2 to document exported functions.
Run devtools::document() to update the NAMESPACE and .Rd files.
Keep examples simple, minimal, and reproducible.
Package documentation is written in English.
NEWS.md is generated by the maintainers just before each release, from the issues of the release milestone: you do not need to edit it per merge request.

📦 Building and checking

Before submitting your merge request, please run: devtools::check()

Try to resolve all errors, warnings, and notes. Neither errors nor warnings are accepted on CI check.

✅ Merge request checklist

My code follows the tidyverse style guide.
I have added or updated documentation.
I have added or updated tests.
The package passes devtools::check() without errors nor warnings.

📜 Code of Conduct

We are committed to providing a friendly and respectful environment. By contributing, you agree to follow the Contributor Covenant.

🚀 Version release procedure

The order of operations for a version vX.Y.Z release (the dev version is vX.Y.Z.90xx):

Merge dev → master — MR entitled “Release vX.Y.Z”, merged by the maintainer.
Bump the release version on master — from vX.Y.Z.90xx to vX.Y.Z with usethis::use_version(which = c("patch", "minor", "major")) at the appropriate level (e.g. "minor" for 0.7.0.9012 → 0.8.0). No release date is added to NEWS.md: the documentation site takes the version date from CRAN.
Run the pre-submission checks (checklist below) and submit to CRAN with devtools::release() (the submission comments live in cran-comments.md at the repository root).
Create the release on GitLab with the vX.Y.Z tag — the tag is pushed to the GitHub mirror automatically by the github_tags CI job.
Merge master → dev — MR entitled “Merge release vX.Y.Z back into dev”.
Do not bump the dev version by hand — the CI pipeline automatically bumps it to the next development series (vX.Y.Z.90xx) and tags it. Check that the pipeline ran.
Check the GitHub mirror is up to date — make sure dev and master there match Forge (push them manually, e.g. git push github dev master, if the branch sync is not automatic), so that the pkgdown site and the CI workflows run on the release.

Pre-submission checks (CRAN)

Following the ThinkR prepare-for-cran checklist:

NEWS.md is generated and complete (all milestone issues, each referenced #NNN).
R CMD check --no-manual --as-cran returns 0 errors / 0 warnings (any remaining NOTE is justified and documented in cran-comments.md).
Spelling: spelling::spell_check_package() clean, inst/WORDLIST updated with the package terms.
URLs: urlchecker reports no dead link.
rhub (v2, on the GitHub mirror): rhub::rhub_check(gh_url, branch) green on the Linux platforms.
cran-comments.md is up to date (changes, checks performed, notes explained, reverse dependencies statement).

Thanks again for helping make airGRiwrm better!