MAINTAINERS.md

In process-analytics/bpmn-visualization-R: Visualize Process Execution Data on 'BPMN' Diagrams

Maintainers

The information provided here are for the maintainers of the project. Contributors should read the Contributing Guide instead.

Merging a Pull Request

A PR can only be merged into master by a maintainer, if all of these conditions are met:

• The CI Checks are passing.
• It has been approved by at least two maintainers. If it was a maintainer who opened the PR, only one extra approval is needed.
• It has no requested changes.
• It is up-to-date with current main branch.

Release process

Maintainers need to perform the following actions in the order described here to push out a release.

⚠️⚠️ First decide whether to publish on CRAN ⚠️⚠️

The CRAN policy states the following:

Submitting updates should be done responsibly and with respect for the volunteers’ time. Once a package is established (which may take several rounds), “no more than every 1–2 months” seems appropriate. ℹ️ For more information, see https://r-pkgs.org/release.html#cran-policies and https://cran.r-project.org/web/packages/policies.html.

But on our end, we can provide more frequent releases. In this case, do not publish to CRAN. The new version will only be available via an installation from GitHub.

Preparing a CRAN submission with rhub

NOTES: required only if we decide to publish to CRAN

Before starting a release, check that the output of the rhub package is stored in cran-comments.md (the most recent output is at the top of the file, and the oldest at the bottom). If this is not the case, you must perform the following steps.

First installation

install.packages("rhub")
library(rhub)

Locally, configure the email address of the maintainer (described in DESCRIPTION): - retrieve the token you previously received by email - call the validate_email.html by passing the maintainer email and the token

If you don't have any token, rhub will prompt you to generate a token (on the first check).

Check

Follow this procedure: https://r-hub.github.io/rhub/articles/rhub.html#prepare-a-cran-submission.

cran_prep <- check_for_cran()

⚠️ Locally, you can only see one run of the environment. To see the other one, you can get the URLs from the top of the local run, and open it on a browser.

Example:

─  Preparing build, see status at
https://builder.r-hub.io/status/bpmnVisualizationR_X.Y.Z.tar.gz-A
https://builder.r-hub.io/status/bpmnVisualizationR_X.Y.Z.tar.gz-B
https://builder.r-hub.io/status/bpmnVisualizationR_X.Y.Z.tar.gz-C

Post processing

In cran-comments.md: - At the top, add this template:

# bpmnVisualizationR <X.Y.Z>.9000

This is a <re-submission | new submission>. In this version, we have:

* <NEW CHANGE>

## Test environments
<RESULT OF check_for_cran()>

## R CMD check results
<RESULT OF check_for_cran()>

## Response to CRAN for last submission

> <CITATION>

• Choose if this is a re-submission or a new submission.
• Add the new change of this version.
• Copy and paste the output of the following command, after receiving the emails for all environments on the maintainer's email address from check_for_cran():

cran_prep$cran_summary()

• In the "Test environments" paragraph, also provides the details of the environment as mentioned in the build status email. For instance, add "Platform: Windows Server 2022, R-devel, 64 bit".
• Remove all Version contains large components (X.Y.Z.9000)" and update the counter of detected NOTE in the summary of all environments
• If this is a re-submission, copy and paste the result for the last CRAN submission, and answer to false NOTES. Otherwise, remove the part:

## Response to CRAN for last submission

> <CITATION>

GitHub issues and milestones update

Note: we always put issues related to a version in a Milestone whose name matches the version.

• Ensure the name of the milestone used for the new release version matches the name of the tag/version that is going to be released. Renamed it if needed.
• Clean this opened milestone if some issues are still opened (move them to a new one or discard milestone from them).
• Close the milestone.
• Create a new milestone for the next version if it does not already exist.

Prepare the GitHub Release Notes

• Open GitHub releases
• Create a new draft release and name it Next (the name is not relevant and will be replaced automatically later). This ensures that development can continue without impacting the writing of the content of the in progress release. That way, if a PR is merged, release-drafter will update the Next draft release keeping the in-progress release untouched.
• The draft release for the newly tagged version should already exist:
• release-drafter creates or updates draft release for the next version each time a pull request is merged to the master branch.
• create a new release if it is missing or rename the existing one to match.
• Ensure that This is a pre-release is unchecked (except if we are releasing alpha, beta, rc, ...)

Initiate the Release

• Open the Release GitHub Actions
• Click on the 'Run workflow' dropdown located on the right side of the page
• Provide parameter value for New version type (default is patch, but you can choose one of the [major | minor | patch])
• Click on the button 'Run workflow'
• Make sure job execution was successful by checking the status
• The new git tag should have been created and available on GitHub

Manual procedure

⚠️⚠️⚠️ Only if the GitHub job that release this repository fails after manual re-run! ⚠️⚠️⚠️

Verify the version in files

Check that the files are using the version to be released: - DESCRIPTION - index (used in the HTML documentation) - README

Create a new PR (it must have the skip-changelog label as we don't want it to appear in the release notes) and merge it, if some files require changes. The PR/commit message should be chore(release): set version to x.y.z.

Once this is done, tag manually with the following command (do not forget to replace x.y.z by the actual version):

git tag -a vx.y.z -m "chore(release): x.y.z"
git push && git push --tags

Use a development version

Add the .9000 suffix to the Version field in the DESCRIPTION file to indicate that this is a development version (for more explanations, see the R documentation). For instance, if the released version was 0.3.0, the Version field in the DESCRIPTION file should be 0.3.O.9000.

Create a new PR (it must have the skip-changelog label as we don't want it to appear in the release notes) and merge it. The PR/commit message should be chore(release): set the development version to x.y.z.9000.

Publish the GitHub Release Notes

• Open the draft release note in GitHub releases
• In the release description (check previous releases as a source of inspiration)
• If the bpmn-visualization TypeScript library was updated, add a phrase about it (for example, see Release 0.3.0 for instance.): The bpmnVisualizationR package now uses [bpmn-visualization@0.29.0](https://github.com/process-analytics/bpmn-visualization-js/releases/tag/v0.29.0).
• Put screenshots/gif of the new features.
• Always mention whether the package is published on CRAN:
• If it is published, add a link to https://cran.r-project.org/package=bpmnVisualizationR
• If it is not published on CRAN (see the 1st paragraph of the release process), please specify this by adding a sentence in bold! The sentence may explain why the new version is not available on CRAN. It should also remind people to install it from GitHub.
• At any time, you can save the draft.
• Only when you are done:
• Assign the tag of the new version as release target and save the draft (doing it as later as possible ensure that release-drafter doesn't interfer with the writing of the Release Notes).
• Publish the release. WARN: if the package is supposed to be published on CRAN, wait for confirmation that the package is actually available on CRAN (see below) before publishing the release notes.

Publish the new version on CRAN

NOTES: required only if we decide to publish to CRAN

Generate and retrieve the source package

It conforms to the CRAN Submission policies first

• Open GitHub Actions
• Find the execution related to the newly created tag
• Choose the tag that has just been created, do not use the main branch!
• If it doesn't exist, click on the 'Run workflow' dropdown located on the right side of the page
  • Remember to choose the tag that has just been created, do not use the main branch!
  • Click on the button 'Run workflow' and wait for the end of the execution
• Download the source package
• in the artifact section, choose the source package built with the r-release version, as shown in the screenshot below 👇
• unzip the artifact to retrieve the tar.gz file that will submit be later

Do the submission

• Fill all the fields of this web form, and load bpmnVisualizationR_X.Y.Z.tar.gz file.
• upload the package tar.gz source previously retrieved
• for all required fields, use the value from the DESCRIPTION file of the tar.gz source (in particular, the name and email of the maintainer of the package are available at the end of the file)
• Submit
• Don't forget to confirm the submission:
• A few minutes after the submission, the package manager should have received an email asking to confirm the submission. The email object looks like CRAN Submission of bpmnVisualizationR 0.3.0 - Confirmation Link
• Confirm the submission by clicking on the link provided in the email
• The submission is only effective when a new email is received from CRAN confirming the submission. The email object looks like CRAN Submission of bpmnVisualizationR 0.3.0

Follow the submission and the CRAN publishing

Once the submission has been confirmed, a CRAN manager examines the packages. While the process is lengthy for new packages, it is much quicker for established ones.

For example, it took some time and many exchanges with maintainers, involving several corrections and explanations, for the first version of the bpmnVisualizationR package to be released as 0.3.2. But the next version, 0.5.0, was accepted 20 minutes after submission.

The maintainer review is sent by email. Please keep an eye on the address used to submit the package.

Accepted submission

When accepted, the email content looks like:

Dear maintainer, thanks, package bpmnVisualizationR_0.5.0.tar.gz is on its way to CRAN.

Then, monitor the package propagation: - the version is first pushed at https://github.com/cran/bpmnVisualizationR/commits/main - the version is actually available when it can be seen at https://cran.r-project.org/package=bpmnVisualizationR

The package for Windows is published several hours or days after. As bpmnVisualizationR doesn't include native code, we can announce the package availability without waiting the Windows flavor.

Rejected submission

If the submission is rejected, a new release is generally required as it involves changing the content of the main branch.

In this case, update the release notes to mention that the version is not available on CRAN (you can explain why) and publish it.

process-analytics/bpmn-visualization-R documentation built on Jan. 25, 2025, 10:34 a.m.