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 :ref:`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 """"""""""" .. code-block:: text $ mkdir scrum Windows """"""" .. code-block:: text > mkdir scrum Creating a card ^^^^^^^^^^^^^^^ A :ref:`card` doesn't need to be in a :ref:`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 """"""""""" .. code-block:: text $ mkdir scrum/backlog Windows """"""" .. code-block:: text > mkdir scrum\backlog Open ``scrum/backlog/card1.md`` in your preferred text editor and add and save the following: ``scrum/backlog/card1.md`` """"""""""""""""""""""""""" .. code-block:: markdown --- summary: My first Scrum card --- We're also going to create a second collection, and add a card to it. macOS/Linux """"""""""" .. code-block:: text $ mkdir scrum/reports Windows """"""" .. code-block:: text > mkdir scrum\reports Open ``scrum/reports/bug.md`` in your preferred text editor and add and save the following: ``scrum/reports/bug1.md`` """"""""""""""""""""""""" .. code-block:: markdown --- 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: .. code-block:: text $ 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: .. code-block:: text $ 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`` """"""""""""""""""""""""" .. code-block:: markdown --- summary: Bug with project reporter: example@example.com severity: High --- # Description Demonstrate another collection of cards ``scrum/reports/bug2.md`` """"""""""""""""""""""""" .. code-block:: markdown --- summary: Bug with project 2 reporter: example@example.com severity: Low --- # Description Nobody cares about this bug ``scrum/reports/bug3.md`` """"""""""""""""""""""""" .. code-block:: markdown --- 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: .. code-block:: text $ 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: .. code-block:: text $ 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: .. code-block:: text $ 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: .. code-block:: text $ 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: .. code-block:: text # 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.toml`` - ``scrum.toml`` - ``pyproject.toml`` See :ref:`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`` """"""""""""""""""""""""" .. code-block:: markdown --- summary: Bad bug reporter: example2@example.com severity: Bad --- If we run ``sbl reports``, we'll see an error: .. code-block:: text $ 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`` """"""""""""""""""""""""" .. code-block:: markdown --- 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`` """"""""""""""""""""""""""" .. code-block:: markdown --- 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: .. code-block:: toml [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: .. code-block:: text $ 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: .. code-block:: text $ 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. .. code-block:: text $ 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. .. code-block:: text $ 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, Tags ^^^^ Cards can be added to additional collections by 'tagging' them. If you add a ``tags`` field, any listed values will be created as a collection. Modify the following cards as follows: ``scrum/reports/bug1.md`` """"""""""""""""""""""""" .. code-block:: markdown --- summary: Bug with project reporter: example@example.com severity: High --- # Tags - tool1 - priority # Description Demonstrate another collection of cards # Fixed by [[card1]] ``scrum/backlog/card1.md`` """"""""""""""""""""""""""" .. code-block:: markdown --- summary: My first Scrum card status: Ready for Development --- # Tags - priority Now, if you were to call ``sbl priority``, you would get the cards with that tag. .. code-block:: text $ sbl priority index, summary card1, My first Scrum card bug1, Bug with project 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: .. code-block:: text $ 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: .. code-block:: text $ 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.