Getting Started¶
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
By default, the yaml template will be populated with the following fields:
bug fix
enhancement
deprecation
removal
performance
documentation
continuous integration
For example, the section for bug-fix will look like this:
bug-fix:
- title: ""
description: ""
You can do anything that is valid yaml in these fields. For example:
bug-fix:
- title: ""
description: |
- Fixed a bug where the program would crash when the user thought of elephants.
- Fixed a bug where the program would ``segfault``
when the user looked at the button.
Adding changed files¶
To add what files have been changed as part of your edit you must edit the
files section. For example:
enhancement:
- description: |
--output-to-console now writes generated release notes to the console.
This is disabled by default.
files:
modified:
- 'src/brassy/brassy.py'
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
modified: test2
deleted: test3
moved: test4
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 -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-09-17)
******************************
* *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 -r or --release-version 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-09-17)
**************************
* *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¶
You can specify the date of the release notes by using 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] (2024-09-17)
******************************
* *Bug fix*: Fixed a bug
Bug fix
=======
Fixed a bug
-----------
This bug was really annoying
::
added: new-test.py
deleted: old/test.py
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/-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] [--output-to-console] [-nr]
[-q]
[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.
--output-to-console Write generated release notes to console.
-nr, --no-rich Disable rich text output
-q, --quiet Only output errors