Tutorial: Basics of using ScrumMD
Note
This tutorial assumes basic skills in your respective command line shell, and that scrummd is either set up globally or in the activate virtual environment.
Creating the repository
Firstly, we’ve got to create a Repository. All that the repository is is a folder that contains your cards. If you’re using ScrumMD to manage a software project, you might choose to keep your repository in the same Git repository as your code, or you might choose to keep them completely separate,
ScrumMD looks for a scrum folder by default. Navigate to where you want to
create the repository and then:
macOS/Linux
$ mkdir scrum
Windows
> mkdir scrum
Creating a card
A Card doesn’t need to be in a Collection, but lets create one anyway. You’re probably going to want one to keep track of them. In Scrum, it’s common to keep all of your cards in backlog, so lets create the backlog folder.
macOS/Linux
$ mkdir scrum/backlog
Windows
> mkdir scrum\backlog
Open scrum/backlog/card1.md in your preferred text editor and add and save
the following:
scrum/backlog/card1.md
---
summary: My first Scrum card
---
We’re also going to create a second collection, and add a card to it.
macOS/Linux
$ mkdir scrum/reports
Windows
> mkdir scrum\reports
Open scrum/reports/bug.md in your preferred text editor and add and save
the following:
scrum/reports/bug1.md
---
summary: Bug with project
reporter: example@example.com
---
# Description
Demonstrate another collection of cards
Viewing the collections
Now, if from our root directory, we call sbl, we’ll get a listing of all of
the Scrum cards:
$ sbl
index, summary
card1, My first Scrum card
bug1, Bug with project
If we wanted just the items in a specific collection, we can call
sbl [collection_name - so:
$ sbl backlog
index, summary
card1, My first Scrum card
Modifying sbl output
If you type sbl --help, you’ll see there are a few ways to modify the
output without even using a configuration file.
We’re going to try customizing the fields being shown, and use grouping. Open the following files in your text editor and modify/create them as listed: following:
scrum/reports/bug1.md
---
summary: Bug with project
reporter: example@example.com
severity: High
---
# Description
Demonstrate another collection of cards
scrum/reports/bug2.md
---
summary: Bug with project 2
reporter: example@example.com
severity: Low
---
# Description
Nobody cares about this bug
scrum/reports/bug3.md
---
summary: Bad bug
reporter: example2@example.com
severity: High
---
# Description
But they care about this one.
If we call sbl reports - we’ll still get something useful:
$ sbl reports
index, summary
bug3, Bad bug
bug2, Bug with project 2
bug1, Bug with project
But - we could group by the Severity by using --group-by severity and add
the output of the reporter with a -c command as follows:
$ sbl reports --group-by severity --columns index,summary,reporter
index, summary, reporter
[severity = high]
bug3, Bad bug, example2@example.com
bug1, Bug with project, example@example.com
[severity = low]
bug2, Bug with project 2, example@example.com
[severity = None]
Board output
Sometimes, it’s helpful to get a more visual representation of the groups in a
collection. By using --output board with sbl or sboard, we can do
this.
For instance - with the example of the bugs above:
$ sboard reports --group-by severity
|high |medium |low |None |
|-------------------|-------------------|-------------------|-------------------|
|bug3 | |bug2 | |
|Bad bug | |Bug with project 2 | |
| | | | |
|bug1 | | | |
|Bug with project | | | |
| | | | |
This can be helpful for showing reports like this, or for viewing the scrum board when grouping by status.
bare mode
Using sbl -b can give a list of relative paths in the collection and nothing
more:
$ sbl reports -b
scrum/reports/bug3.md
scrum/reports/bug2.md
scrum/reports/bug1.md
If you’re using bash or similar as your shell, you are then able to call
sbl -b in backticks as the parameter to a text-editor to load all the
cards at once. For instance - if you were refining the bug reports, you could
use ``vim sbl reports -b `` to load all the bug reports in vim.
Viewing cards
ScrumMD comes with scard which will give you a full output of the referenced
cards:
# sbl bug1 bug2 bug3
---
bug1: Bug with project
---
reporter: example@example.com
severity: High
description:
Demonstrate another collection of cards
---
bug2: Bug with project 2
---
reporter: example@example.com
severity: Low
description:
Nobody cares about this bug
---
bug3: Bad bug
---
reporter: example2@example.com
severity: High
description:
But they care about this one.
Configuration
Configuration is in toml files. ScrumMD looks for configuration in the
following files (in this order):
.scrum.tomlscrum.tomlpyproject.toml
See Configuration for more details.
We’re going to use the configuration to limit the allowed values of
severity. Create the following file in the same directory that contains
scrum.
scrum.toml
..text-block:: toml
[tool.scrummd] strict = true
[tool.scrummd.fields] severity = [“High”, “Medium”, “Low”]
This set some permitted values for severity, and enabled strict mode:
meaning that if there are any errors, the programs will refuse to run.
Now, create the following file:
scrum/reports/bug4.md
---
summary: Bad bug
reporter: example2@example.com
severity: Bad
---
If we run sbl reports, we’ll see an error:
$ sbl reports
ERROR:root:ValidationError (severity is "Bad". Per configuration, severity must be one of [High, Medium, Low]) reading scrum/reports/bug4.md
Delete bug4.md before continuing on the tutorial.
References
You can add references to a card by referring to its index/card number in
double-square brackets - like [[bug01]].
By default - scard will replace it with a reference to the index and the
summary - but, this can be configured to include another field. For instance,
you might use the configuration to include the status field of the card.
Firstly, we’ll modify the following file to add a reference:
scrum/reports/bug1.md
---
summary: Bug with project
reporter: example@example.com
severity: High
---
# Description
Demonstrate another collection of cards
# Fixed by
[[card1]]
We’ll add a status to card by modifying the following file:
scrum/backlog/card1.md
---
summary: My first Scrum card
status: Ready for Development
---
Next, we’ll change the references in the config to suit our fields. Modify
scrum.toml as follows:
[tool.scrummd]
strict = true
[tool.scrummd.scard]
reference_format = "$index [$status]"
[tool.scrummd.fields]
severity = ["High", "Medium", "Low"]
status = ["Ready For Development", "In Progress", "Done"]
We added a reference format, and expected values for the status.
Now, if we go scard bug1, we’ll see:
$ scard bug1
---
bug1: Bug with project
---
reporter: example@example.com
severity: High
description: Demonstrate another collection of cards
fixed by:
card1 - My first Scrum card [Ready for Development]
You’ll see that the reference has been replaced with a more useful reference.
Filters
Now you’ve got some bugs (sorry), you might want to see just the highest
severity bugs. sbl has filters available with --include.
You can add multiple filters with multiple --include statements (all of
which must be matched to show), and multiple values to include by separating
them with a comma. If you were to go:
$ sbl --include severity=high
index, summary
bug3, Bad bug
bug1, Bug with project
You can see that just high severity bugs are returned. Alternatively - you could
go sbl --include severity=high,medium to show all medium and high bugs.
Sorting
Sorting can be a helpful thing to do. If instead of filtering our bugs, we
wanted to sort them priority, we can use --sort-by statements.
$ sbl --sort-by severity --columns "index, summary, severity"
index, summary, severity
card1, My first Scrum card,
bug3, Bad bug, High
bug1, Bug with project, High
bug2, Bug with project 2, Low
Multiple --sort-by statements can be combined, and you can use ^ to
reverse the order.
$ sbl --sort-by ^severity --columns "index, summary, severity"
index, summary, severity
bug2, Bug with project 2, Low
bug3, Bad bug, High
bug1, Bug with project, High
card1, My first Scrum card,
Card defined collections
Cards can define their own collections and sub-collections. Any time a card
is referenced in a field, that field an be used as a collection. For instance,
if you’ve been following this tutorial, bug1 has a collection called
bug1.fixed by due to [[card1]] being in the fixed by field:
$ sbl "bug1.fixed by"
index, summary
card1, My first Scrum card
bug1, Bug with project
Further - as all sub-collections are included in their parent collections,
bug1 is a collection by itself:
$ sbl bug1
index, summary
card1, My first Scrum card
bug1, Bug with project
You can create an items field if you wish to add cards to the collection
without creating a sub-collection.
Conclusion
You have seen how to set up a basic repository, do some basic configuration, add some cards, and seen some ways of interacting with them.
There should be enough tools here for you to go off and start managing your cards with ScrumMD.