Package: branchnews
branchnewshelps you use branch-based file names withtowncrier.
It is designed for use with GitHub, but can probably work with other collaboration
platforms as well.If you are not already familiar withtowncrier,
it is a great tool for generating changelogs, based onnews fragment files.However, a difficulty arises if you want
to record a news fragment for a PR (pull request) that does not correspond to an
existing issue.
In such cases, it is hard to choose a name for the fragment file while preparing
the PR, because you do not know the number the PR will receive, until after it has
already been opened.The solution provided bybranchnewsis to let you instead record the fragment
under a filename based on your GitHub username and the name of your topic branch,
like this:USERNAME.BRANCHNAME.branchnews.NEWS_TYPE.txtThe$ branchnews createcommand helps you generate this file.Later, when you are ready to generate a changelog withtowncrier, first use the$ branchnews renamecommand to automatically rename the fragment files, so that they now incorporate
the correct PR numbers.RequirementsThe$ branchnews renamecommand usesgit login order to
associateUSERNAME/BRANCHNAMEcombinations
with the PR numbers that were eventually assigned. In order for this to work, you must
observe the following rules in your development process:Each time a PR is merged, you must accept the standard GitHub merge commit message of the form,Merge pull request #NUMBER from USERNAME/BRANCHNAMENo single GitHubUSERNAMEmay reuse a givenBRANCHNAMEfor two or more separate
PRs, within a given release cycle. (This is probably just good practice anyway.)Furthermore, for the sake of simplicity, the$ branchnews createcommand requires you to
have aconfiguredfragments directory, in yourtowncrierconfig. That is,Yourtowncrierconfig must define thedirectorykey.Seehttps://towncrier.readthedocs.io/en/stable/configuration.html.UsageConfigurationbranchnewsdoes not currently support any configuration options of its own, but it
does rely on yourtowncrierconfiguration.
As stated above, you must at least define thedirectorykey.Furthermore, you probablyshoulddefine theissue_formatkey in the way
indicatedhere, i.e.
like this:issue_format="[#{issue}](https://github.com/example/my-project/issues/{issue})"so that issue and PR numbers link to the appropriate pages at GitHub.
(If you didn't want your  changelog entries to link to those pages, there was probably no
reason to be usingbranchnewsin the first place.)Note: Theissue_formatsuggested above will work for both issuesandPRs.
GitHub automatically redirects URLs ending withissues/NNNtopull/NNNwhen the number
in fact belongs to a PR, not an issue.Preparing a PRWhen any contributor to your project is preparing a PR, they should generate a news
fragment file by invoking$ branchnews createand then following the on-screen prompts.The very first prompt asks if there is an associated issue number. This is so that this one
procedure can be used whether there is an issue number or not.A session for which thereisan associated issue number might look like this:$ branchnews create
Issue number (leave blank to use branch name instead): 1234
What type of news is it?
(0): security
(1): removed
(2): deprecated
(3): added
(4): changed
(5): fixed
Type: 3
Created 1234.added.txt
Please edit the file to provide a release note.(The menu of alternatives for the newstypeis generated directly from yourtowncrierconfig.)A session for which there isnotan associated issue number might look like this:$ branchnews create
Issue number (leave blank to use branch name instead): 
GitHub username: example
Branch name is fix-that-pesky-bug
What type of news is it?
(0): security
(1): removed
(2): deprecated
(3): added
(4): changed
(5): fixed
Type: 5
Created example.fix-that-pesky-bug.branchnews.fixed.txt
Please edit the file to provide a release note.After generating the file, the contributor should edit it, recording the desired
news entry, and thengit committhe file, before opening a PR.Note that Git allows a wide variety of symbols to appear in branch names (including
slashes and dots), and this is no problem withbranchnews.
The branch name is percent-encoded before becoming a segment of the generated filename.Generating a change logBefore you can generate your changelog withtowncrier, first use$ branchnews renameto automatically rename all the fragment files having names of the formUSERNAME.BRANCHNAME.branchnews.NEWS_TYPE.txt. After renaming, they will instead
have names of the formNNN.NEWS_TYPE.txt, where the correct PR numberNNNhas
been obtained usinggit log.Remember, this will only work if you have followed the rules stated above,
underRequirements. In case there were any lapses (maybe one time
you failed to accept the standard merge commit message for a PR), then thebranchnews renamecommand will still automatically rename all the files it can,
and it will also print a list of those files that it could not rename. Using theUSERNAMEandBRANCHNAMEfor any such files, you should be able to manually
track down the right PR numbers.Thebranchnews renamecommand will also automaticallystagethe renames, but
it will not perform a commit. You should do the commit manually (maybe with a
simple commit message like, "Rename branchnews files").After committing the renames, you can proceed to usetowncrieras normal.