Skip to contents

Release process

Source: RELEASING.md

gaussianprocesses uses R package versions of the form MAJOR.MINOR.PATCH. Development versions on the default branch append .9000, for example 0.1.0.9000.

From 1.0.0 the versions follow semantic versioning, as set out under “Stability and versioning” in CONTRIBUTING.md:

  • Major releases may change stable interfaces incompatibly, including removing deprecated names.
  • Minor releases add features, deprecate stable names, and may change experimental interfaces.
  • Patch releases only fix defects, compatibly.

Below 1.0, minor releases may also contain documented breaking changes to stable interfaces.

The release after 0.1.0 is 1.0.0, the first on CRAN (#40). It removed the names deprecated after 0.1.0 without a release of warnings; NEWS says so.

Releases are listed on the GitLab releases page. Nothing is ever published automatically: pushes, merge requests, schedules, and tags never publish a release.

1. Prepare

Prepare the release in a normal merge request.

  1. Version. Choose the version by the rules above:

    • a patch release only if nothing but compatible fixes changed;
    • a minor release for new features, deprecations, and changes to experimental interfaces;
    • a major release for incompatible changes to stable interfaces.

    Set Version: in DESCRIPTION to it, without the .9000 suffix.

  2. Release notes. Rename the # gaussianprocesses (development version) heading in NEWS.md to # gaussianprocesses X.Y.Z and review its entries. These lines become the release notes. Check that they list:

    • every change to an experimental interface;
    • every new deprecation;
    • in a major release, every removal.

  3. Documentation. Regenerate the reference pages and NAMESPACE, then rebuild the site and review it in public/:

    roxygen2::roxygenise()
pkgdown::build_site()

  4. Local tests.

    testthat::test_local()

  5. R CMD check. From the repository root:

    R CMD build .
R CMD check --as-cran gaussianprocesses_X.Y.Z.tar.gz

    devtools::check() is equivalent. There must be no ERROR or WARNING. Only CRAN-incoming NOTEs are expected, such as the one for a package that is not yet on CRAN.

    The tests also check the stability tiers and the model format: every export has a tier on its help page and in the reference index, and models saved by 0.1.0 and schema-4 models are read and give the same results.

  6. Merge. Make sure the merge-request pipeline passes, merge, and confirm that the default-branch pipeline passes and the Pages site deploys.

2. CRAN submission

CRAN receives the built source tarball, not the working tree. Check the tarball that will be submitted, and submit only after every check below is clean.

  1. CRAN checks in CI. Start a manual pipeline for the release-candidate commit with CRAN_CHECK=true.
    • The cran-check job installs every package in Suggests and runs R CMD check --as-cran on the built tarball with its tests, as CRAN does.
    • The text-checks job runs the spelling and URL checks (ci/text-checks.R). Add correctly spelled words to inst/WORDLIST.
  2. Local checks. On the tarball, from a clean copy of the tree:
    • _R_CHECK_CRAN_INCOMING_=true R CMD check --as-cran should report only the “New submission” NOTE on a first submission, and nothing for later versions.
    • _R_CHECK_DEPENDS_ONLY_=true R CMD check --as-cran checks that suggested packages are used only conditionally.
  3. Platform checks. Submit the same tarball to: The results are emailed to the maintainer address in DESCRIPTION. Link them in the release issue.
  4. Submission comments. Update cran-comments.md with the environments and results from steps 1 to 3, and remove every pending marker.
  5. Name. Check again that no current or archived CRAN package, and no current Bioconductor package, has the same name, ignoring case.
  6. Submit. Upload the tarball with the CRAN submission form, paste cran-comments.md as the comments, and confirm the email CRAN sends to the maintainer. Do not submit again while a submission is pending.

The target is no ERRORs, no WARNINGs, and no NOTEs except “New submission”. Explain any unavoidable NOTE in the comments.

Resubmission

If CRAN asks for changes:

  1. Fix them in a merge request, and answer each point under a ## Resubmission heading at the top of cran-comments.md.
  2. Increase the version if the reviewers ask for it; otherwise keep it, since the version was not published.
  3. Repeat steps 1 to 4 on the new tarball.
  4. Submit with the same form, noting in the comments that it is a resubmission.

After acceptance, tag and publish the GitLab release from the accepted commit (section 3).

3. Publish

Releases are published only from a manually started pipeline on main. Open Build > Pipelines, select New pipeline, choose main, and add the variable RELEASE_TAG=vX.Y.Z. These links open the form prefilled; replace X.Y.Z first:

  • Dry run, which runs every check and publishes nothing: https://gitlab.com/DiogoRibeiro7/gaussian-processes-r/-/pipelines/new?ref=main&var[RELEASE_TAG]=vX.Y.Z&var[RELEASE_DRY_RUN]=true
  • Release: https://gitlab.com/DiogoRibeiro7/gaussian-processes-r/-/pipelines/new?ref=main&var[RELEASE_TAG]=vX.Y.Z

The release job runs only after the check and docs stages succeed, and release jobs are serialized with a resource group. It uses the CI job token; no personal token or CLI installation is needed.

Before publishing anything, the job checks that:

  • RELEASE_TAG is v followed by the exact DESCRIPTION version;
  • NEWS.md contains a non-empty # gaussianprocesses X.Y.Z section;
  • the source tarball built by r-cmd-check exists;
  • the tag either does not exist yet or already points at the pipeline commit;
  • no release with this tag exists.

It then:

  1. uploads gaussianprocesses_X.Y.Z.tar.gz to the project’s generic package registry;
  2. creates the GitLab release, with the NEWS.md section as its notes and the tarball as an asset;
  3. creates the annotated tag vX.Y.Z at the pipeline commit if it does not already exist.

Tags are immutable: never move or delete a published tag. The guards are tested by ci/tests/release-test.sh, which uses a temporary local repository and never contacts GitLab.

Without GitLab CI

If CI is unavailable, publish the same release by hand from an up-to-date main:

R CMD build .
R CMD check --as-cran gaussianprocesses_X.Y.Z.tar.gz
git tag --annotate vX.Y.Z --message "gaussianprocesses X.Y.Z"
git push origin vX.Y.Z

Then create a release for the tag under Deploy > Releases, paste the NEWS.md section as its notes, and attach the tarball.

4. After the release

In a new merge request, bump Version: to the next development version (for example 1.0.0.9000) and add a new # gaussianprocesses (development version) heading at the top of NEWS.md.

Verify installation

Download the source package from the release assets and install it:

install.packages("gaussianprocesses_X.Y.Z.tar.gz", repos = NULL, type = "source")
packageVersion("gaussianprocesses")