Syntax Reference - GitHub
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 afeature/**
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
put-on-files | with-modification | file before change | file after change | is task applied |
---|---|---|---|---|
** | added | not there | some-name.txt |
✅ |
** | modified/deleted | not there | some-name.txt |
❌ |
name-after.txt | added | name-before.txt |
name-after.txt |
✅ |
name-after.txt | modified/deleted | name-before.txt |
name-after.txt |
❌ |
name-before.txt | added/modified | name-before.txt |
name-after.txt |
❌ |
name-before.txt | deleted | name-before.txt |
name-after.txt |
✅ |
** | deleted | some-name.txt |
not there | ✅ |
** | added/modified | some-name.txt |
not there | ❌ |
other-name.txt | added/modified/deleted | some-name.txt |
some-name.txt |
❌ |
some-name.txt | modified | some-name.txt |
some-name.txt |
✅ |
some-name.txt | added/deleted | some-name.txt |
some-name.txt |
❌ |
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 withfeature/
.
--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 withbugflix/
.
--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/...
orbeta
--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 filesfoo/*
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 examplerefs/heads/PROJECT-1234
){option1,option2,optionX}
provides list of options which can be matched. e.g.main.{java,js,ts}
matchesmain.java
,main.js
ormain.ts
.{master,release/*}
matches branches likemaster
,release/1.0
,release/2.0
....