Syntax Reference

You can find below the syntax used to enrich your pull requests with Pull Request Checklist Buddy by adding items to your PRCHECKLIST file.

Use our Online Checklist Editor to get started with your first checklists. You can also upload existing PRCHECKLIST files and edit them with our easy-to-use UI.

Tasks and Comments

Create a task

To create a new task, use +task+ followed by the task description.

+task+ this is a task.

Create a comment

To create a reminder (a non-blocking comment), use +comment+ followed by the comment text. Bitbucket markdown is supported for comments.

+comment+ this is a comment.

Longer tasks and comments

Both tasks and comments can have multiple lines. You can make a line break by ending the line with a \.

+task+ This is a long task description \
  that will span multiple lines

Create a checklist

A checklist is created automatically for each set of tasks that include the same filters and modifiers.

Filter

To filter when a task is applied, prepend the task/comment/title with one or more of the following filters:

• --source - for pull requests for which the source branch matches a specific pattern (see the Glob format section below)

 --source my-branch +task+ this is a task for all PRs that originate from the branch my-branch

• --target - for pull requests for which the target/destination branch matches a specific pattern (see the Glob format section below)

 --target master +task+ This is a task for all PRs targeting the master branch   

• --files - for pull requests for which changes have been made to files matching a diff file pattern (see the Glob format section below)

 --files /src/main/app/** +task+ This is a task for all PRs with changes in files within /src/main/app/

• --commit-title - for pull requests with commit titles (first line of commit message) that contain a substring

 --commit-title WIP +task+ Improve/cleanup commit message for Work-in-Progress (WIP) commits

Note: entries with the same filter settings will be grouped together into a checklist, regardless of their position in the PRCHECKLIST file

Negation filters with -except modifier

Each of the filters above can be rather used as an exception rule by appending the -except modifier. For example,

• --source-except - for pull requests for which the source branch does not match a specific pattern

  --source-except my-branch +task+ this is a task for all PRs that do not originate from the branch my-branch

• --files-except - for pull requests for which no files matching the diff file pattern have been changed.

  --files-except version.txt +task+ did you forget to update the version?

• --commit-title-except - for pull requests where no commit title contains a substring

 --commit-title-except MY-PROJ- +task+ This is a task for all PRs that miss a Jira project key in **any** of the commit titles

• A combination of --source and --files-except - you can have a use case where all pull requests coming from a feature/** branch have to update the release notes. You can address that use case via

  --source feature/** --files-except RELEASENOTES.txt +task+ did you forget to update the release notes?

Further Options

By default, each checklist is displayed once on the entire Pull Request. Checklist Buddy gives you a bit of flexibility to change that behaviour. For example,

• --put-on-files - to apply your checklist on each file matching the diff file pattern, but only if these files are changed in the pull request.

  --put-on-files RELEASENOTES.txt +task+ Please ask QA to review these changes

• --with-modification - to be used after the --put-on-files option to only apply the checklist when the impacted file underwent a specific type of change. The three possible types of change are "added", "modified" or "deleted". The table below summarizes when these change types will be applied to a file diff. You may use any combination of the three types of change.

  --put-on-files CODEOWNERS --with-modification deleted --with-modification modified +task+ When deleting this file, no Code Owners will be assigned anymore and your repo will be unprotected. Changes to this file should be carefully reviewed.
  --put-on-files src/** --with-modification added +task+ Please double check that the location of the new file corresponds to our Package by Feature guideline

Give a title to your checklist

To name a checklist, create a line entry with the desired filter settings and use +title+ followed by the desired title.

Similar to comments and tasks, titles can span multiple lines using the same \ syntax

+title+ This is a long title \
  spanning on multiple lines

Examples

• The following creates a checklist called Checklist Buddy release checklist. It applies for pull requests targeting the master branch and includes 3 tasks and 1 comment.

--target master +title+ **[CHECKLISTBUDDY](https://marketplace.atlassian.com/apps/1225571/pull-request-checklist-buddy-for-bitbucket?hosting=datacenter&tab=overview) release checklist** :checkered_flag:
--target master +task+ Bump version number
--target master +task+ Internal release testing: \
  https://wiki/display/CHECKLISTBUDDY/Releases \
  All test cases: https://wiki/display/CHECKLISTBUDDY/Manual+testing have been checked off on the release page or have been confirmed by the team for ignoring
--target master +task+ Public documentation (https://docs.mibexsoftware.com/checklist-buddy/) and Public release notes (https://docs.mibexsoftware.com/checklist-buddy/release-notes) are up to date
--target master +comment+ All done? merge PR with --ff-only .

• The following creates a checklist called Frontend testing checklist. It applies to pull requests that include changes to files located in the /src/main/app/** folder of the repository and includes 4 tasks.

--files /src/main/app/** +title+ Frontend testing checklist :art:
--files /src/main/app/** +task+ UI changes visually inspected on Chrome
--files /src/main/app/** +task+ UI changes visually inspected on Safari 
--files /src/main/app/** +task+ UI changes visually inspected on Firefox
--files /src/main/app/** +task+ UI changes visually inspected on IE/Edge (reply with version)

• The following creates a task called User Documentation updated? for all pull requests that target the branch master and for which the source branch name starts with feature/.

--target master --source feature/* +task+ User Documentation updated?

• The following creates a task called Verify that automated test reproduces this issue for all pull requests that target branches whose name starts with bugfix/.

--target bugfix/* +task+ Verify that automated test reproduces this issue.

• The following creates a task called Double check with the Release Manager if this change is required for the release for all pull requests that target a branch whose name starts with release/ and for which the source branch name does NOT start with bugflix/.

--target release/* --source-except bugfix/* +task+ Double check with the Release Manager if this change is required for the release.

• Create a task only for pull requests with destination branches master, release/... or beta

--target {master,release/*,beta} +task+ User documentation updated?

Glob format

Lots of matching rules in Checklist Buddy use the glob format. This format is used by many tools, including Git, to match file paths. For example, you can specify matching rules for source or target branches, or modified files.

Below, we summarize the most important rules.

• * matches any number of characters, but not /
• ** matches any number of characters, including /
• ? matches exactly one character, but not /
• **/*.java matches all java files
• foo/* matches all files or branches ending with /foo/ (or starting with foo/) followed by any number of characters except '/'
• bar/ matches all files or branches containing /bar/ (or starting with bar/)
• /bar/ matches all files or branches starting with bar/
• PROJECT-* matches all files or branches named PROJECT-*, even after a / (for example refs/heads/PROJECT-1234)
• {option1,option2,optionX} provides list of options which can be matched. e.g. main.{java,js,ts} matches main.java, main.js or main.ts. {master,release/*} matches branches like master, release/1.0, release/2.0 ....