Using Brassy¶
Example usage¶
Create YAML template¶
Brassy can create blank yaml templates for release notes.
By default, brassy will name the file after your current git
branch name. You can also specify a name manually, and
.yaml will be appended if you do not end your file name with
.yml or .yaml. You can do this with the following command:
brassy --write-yaml-template release-note.yaml
# or
brassy -t release-note.yaml
# or leave blank to name after current git branch
brassy -t
By default, the yaml template will be populated with the following fields:
bug fix
enhancement
deprecation
removal
performance
documentation
continuous integration
You can configure this in your .brassy file. See also Settings.
For example, the section for bug-fix will look like this:
bug fix:
- title: ''
description: |
files:
deleted:
- ''
moved:
- ''
added:
- ''
modified:
- ''
related-issue:
number: null
repo_url: ''
date:
start: null
finish: null
For example:
bug fix:
- title: 'Fix elephant related crash'
description: |
- Fixed a bug where the program would crash when the user thought of elephants.
description: |
files:
deleted:
- 'die-on-thoughts.py'
moved:
- ''
added:
- ''
modified:
- 'main.py'
related-issue:
number: 1938
repo_url: 'http://github.com/fake/repo'
date:
start: "10-10-1999"
finish: "02-21-2026"
Generating the changed files via git¶
You can run brassy with --get-changed-files (or -c)
to output the files that have been
modified, added, deleted or moved in the current branch as compared to the main
branch. It runs on the current directory by default,
but it accepts a path as an argument.
For example, the output looks like this:
brassy --get-changed-files
added:
- test.py
modified:
- test2.js
deleted:
- test3.cpp
moved:
- test4.fortran
It prints with indents for easy copy-and-pasting into your yaml files.
Generate release notes¶
Once you have filled out your yaml template, you can generate release notes with the following command:
brassy --output-file new-release-note.rst release-note.yaml
brassy -o new-release-note.rst release-note.yaml
For example, if release-note.yaml contains the following:
bug fix:
- description: "This bug was really annoying"
files:
added:
- "new-test.py"
deleted:
- "old/test.py"
related-issue:
number: 0
repo_url: ''
title: "Fixed a bug"
The output will be:
Version [UNKNOWN] (2024-10-22)
**************************
* *Bug fix*: Fixed a bug
Bug fix
===========
Fixed a bug
-------------------------
This bug was really annoying
::
added: new-test.py
deleted: old/test.py
Specifying Version¶
You can specify the version of the release notes by using the
--release-version or -r flag.
For example, using the previous yaml file:
brassy -o new-release-note.rst release-note.yaml -r 1.0.0
Which would output:
Version 1.0.0 (2024-10-22)
**************************
* *Bug fix*: Fixed a bug
Bug fix
===========
Fixed a bug
-------------------------
This bug was really annoying
::
added: new-test.py
deleted: old/test.py
Specifying Date¶
By default, brassy uses todays date in YYYY-MM-DD format.
You can specify the date of the release notes in any format
with the -d or --release-date flag.
For example, using the previous yaml file:
brassy -o new-release-note.rst release-note.yaml -d 3000-30-30
Which would output:
Version [UNKNOWN] (3000-30-30)
**************************
* *Bug fix*: Fixed a bug
Bug fix
===========
Fixed a bug
-------------------------
This bug was really annoying
::
added: new-test.py
deleted: old/test.py
Change YAML directory¶
By default brassy works in your current working directory.
You can specify a directory with --yaml-dir or -yd.
For example:
brassy --yaml-dir ./docs/release-notes/v1.0.0 \
--write-template "updating-gpu-code"
would write a template file updating-gpu-code.yaml
to ./docs/release-notes/v1.0.0.
Prune YAML file¶
Brassy can “prune” yaml files by removing blank sections. Sections are considered blank if all of their items are blank OR are empty lists.
For example:
bug fix:
- title: 'Real issue'
description: 'Questionably real description.'
files:
deleted:
- ''
moved:
- ''
added:
- ''
modified:
- 'fake_file.py'
related-issue:
number: 100000
repo_url: ''
date:
start: null
finish: null
would become
bug fix:
- title: Real issue
description: Questionably real description.
files:
modified:
- fake_file.py
related-issue:
number: 100000
after pruning.
To prune a file, pass it to brassy with --prune.
Eg. brassy --prune fake_file.yaml
Controlling CLI Output¶
You can turn off fancy formatting (colors, bold, etc.)
by using the --no-color/-nc flag.
You can also turn off all non-error outputs by using the --quiet or -q flag.
Help!¶
When in doubt, you can always run the help command to see what options are available:
brassy --help
Which outputs:
Usage: brassy [-h] [-t [WRITE_YAML_TEMPLATE]] [-c [GET_CHANGED_FILES]]
[-r VERSION] [-d RELEASE_DATE] [-nc] [-p PREFIX_FILE]
[-s SUFFIX_FILE] [-o OUTPUT_FILE] [-yd YAML_DIR]
[--output-to-console] [-nr] [-q] [-pr] [--init] [--version]
[input_files_or_folders ...]
Generate release notes from YAML files. Entries are sorted by order in yaml
files, and by order of yaml files provided via the command line.
Positional Arguments:
input_files_or_folders
The folder(s) containing YAML files and/or YAML files.
Folders will be searched recursively.
Options:
-h, --help show this help message and exit
-t, --write-yaml-template [WRITE_YAML_TEMPLATE]
Write template YAML to provided file. If folder
provided, place template in folder with current git
branch name as file name.
-c, --get-changed-files [GET_CHANGED_FILES]
Print git tracked file changes against main. If
directory provided, use that directories checked-out
branch.
-r, --release-version VERSION
Version number of the release. Default is '[UNKNOWN]'.
-d, --release-date RELEASE_DATE
Date of the release. Default is current system time.
-nc, --no-color Disable text formatting for CLI output.
-p, --prefix-file PREFIX_FILE
A header file to prepend to the release notes.
-s, --suffix-file SUFFIX_FILE
A footer file to suffix to the release notes.
-o, --output-file OUTPUT_FILE
The output file for release notes.
-yd, --yaml-dir YAML_DIR
Directory to write yaml files to
--output-to-console Write generated release notes to console.
-nr, --no-rich Disable rich text output
-q, --quiet Only output errors
-pr, --prune Prune provided yaml file(s) of empty sections
--init Initialize brassy and generate config files
--version Print program version and exit