Topics

#changelog #generator #github #github-api #productivity #python #zenhub #zenhub-api

Language breakdown

No language data available.

▸ Files click to expand

README

Loghub

Project details

Build status

Description

Changelog generator based on milestone or tags for github.

Example output

So how does this look in practice? It looks like this for 0.3 release of loghub:

## Version 0.3 (2017-10-10)
Issues Closed
Enhancements
Issue 63 - Add PR link / commit link inside issue (PR 69)

In this release 1 issue was closed.
Pull Requests Merged
PR 69 - PR: Add extra links for related issues and prs (63)

In this release 1 pull request was closed.

You can look at loghub's CHANGELOG.md, or spyder's CHANGELOG.md for a more complete example output.

Installation

Using pip

pip install loghub


Using conda

<pre><code class="lang-bash">conda install loghub -c conda-forge</code></pre>

or

conda install loghub -c spyder-ide

Usage

loghub can be used to generate changelog based on milestones or on tags.

In projects where milestones are used to track a release we can use for example:

loghub spyder-ide/spyder --milestone v3.0

In projects where milestones are used to track chunks of work but not releases, we can use tags to get the changes after the latest release, for example:

loghub spyder-ide/spyder --since-tag v3.0.0b7

Or if loghub is used to generate old changelogs (or update changelogs), we can also use tags to limit the range , for example:

loghub spyder-ide/spyder --since-tag v3.0.0b7 --until-tag v3.0.0

For private repos, just add the username and password arguments, for example:

loghub spyder-ide/spyder --since-tag v3.0.0b7 --since-tag v3.0.0 --username <username> --password <password>

Or, just add the username and a password prompt will appear, for example:

loghub spyder-ide/spyder --since-tag v3.0.0b7 --since-tag v3.0.0 --username <username>

Or generate a Github access token and use that instead, for example:

loghub spyder-ide/spyder --since-tag v3.0.0b7 -until-tag v3.0.0 --token <token>

Important

Because of the Github API rate limitations it is advised to always use authentication by either access token or user and password.

ZenHub Integration

If your project is using Zenhub to manage the workflow, you can also use Zenhub releases to create your changelog.

loghub spyder-ide/spyder --zenhub-release "spyder v4.1.0" --zenhub-token <zenhub-token>

Important

For Zenhub integration to work you need to always use a zenhub token. You can generate one by going to your dashboard. Same GitHub API rate limits apply here so it is advised to always use authentication by either access token or user and password.

loghub spyder-ide/spyder --zenhub-release "spyder v4.1.0" --zenhub-token <zenhub-token> --token <github-token>

Advanced Usage

Filter PR base branch

Pull requests to display can be filtered depending on the branch they were merged against (base branch):

loghub spyder-ide/spyder --branch 3.x

Filter issues/PRs by labels

To filter issues to display, we can use a regular expression:

loghub spyder-ide/spyder --issue-label-regex "Type.*" --milestone v3.1

This will filter all the issues that start with Type

The same can be done with PRs

loghub spyder-ide/spyder --pr-label-regex "<some-regex>" --milestone v3.1

Group issues by label

Issues displayed can be grouped by labels:

loghub spyder-ide/spyder --issue-label-group "Type-Bug" "Bugs Fixed" --issue-label-group "Type-Enhancement" "New Features" --milestone v3.1

This will result in issues being grouped in two sections with the headings Bugs Fixed and New Features respectively.

Output format

Loghub provides two formats:

changelog, which is the default and includes links to issues and PRs
release, which does not include links

loghub spyder-ide/spyder --milestone v3.1 --format release

Custom templates

Loghub uses Jinja2 templates to format the output. If the current template does not meet your needs, you can copy the default templates <https://github.com/spyder-ide/loghub/tree/master/loghub/templates>_ and create a new one and provide the path to it as:

loghub spyder-ide/spyder --milestone v3.1 --template <PATHTOTEMPLATE>

Detailed CLI arguments

usage: loghub [-h] [-u USERNAME] [-p PASSWORD] [-t TOKEN] [-zt ZENHUB_TOKEN] [-m MILESTONE] [-zr ZENHUBRELEASE] [-st SINCETAG] [-ut UNTIL_TAG] [-b BRANCH] [-ilg ISSUELABELGROUPS [ISSUELABELGROUPS ...]] [-plg PRLABELGROUPS [PRLABELGROUPS ...]] [-lg LABELGROUPS [LABELGROUPS ...]] [-ilr ISSUELABELREGEX] [-plr PRLABELREGEX] [-f OUTPUT_FORMAT] [--template TEMPLATE] [--batch {milestones,tags}] [--no-prs] repository Script to print the list of issues and pull requests closed in a given milestone, tag including additional filtering options. positional arguments: repository Repository name to generate the Changelog for, in the form user/repo or org/repo (e.g. spyder-ide/spyder)

optional arguments: -h, --help show this help message and exit -u USERNAME, --username USERNAME Github user name -p PASSWORD, --password PASSWORD Github user password -t TOKEN, --token TOKEN Github access token -zt ZENHUBTOKEN, --zenhub-token ZENHUBTOKEN Zenhub access token -m MILESTONE, --milestone MILESTONE Github milestone to get issues and pull requests for -zr ZENHUBRELEASE, --zenhub-release ZENHUBRELEASE Zenhub release to get issues and pull requests for -st SINCETAG, --since-tag SINCETAG Github issues and pull requests since tag -ut UNTILTAG, --until-tag UNTILTAG Github issues and pull requests until tag -b BRANCH, --branch BRANCH Github base branch for merged PRs -ilg ISSUELABELGROUPS [ISSUELABELGROUPS ...], --issue-label-group ISSUELABELGROUPS [ISSUELABELGROUPS ...] Groups the generated issues by the specified label. This optiontakes 1 or 2 arguments, where the first one is the label to match and the second one is the label to print on the finaloutput -plg PRLABELGROUPS [PRLABELGROUPS ...], --pr-label-group PRLABELGROUPS [PRLABELGROUPS ...] Groups the generated PRs by the specified label. This optiontakes 1 or 2 arguments, where the first one is the label to match and the second one is the label to print on the finaloutput -lg LABELGROUPS [LABELGROUPS ...], --label-group LABELGROUPS [LABELGROUPS ...] Groups the generated issues and PRs by the specified label. This option takes 1 or 2 arguments, where the first one is the label to match and the second one is the label to print on the final output -ilr ISSUELABELREGEX, --issue-label-regex ISSUELABELREGEX Label issue filter using a regular expression filter -plr PRLABELREGEX, --pr-label-regex PRLABELREGEX Label pull request filter using a regular expression filter -f OUTPUTFORMAT, --format OUTPUTFORMAT Format for print, either 'changelog' (for Changelog.md file) or 'release' (for the Github Releases page). Default is 'changelog'. The 'release' option doesn't generate Markdown hyperlinks. --template TEMPLATE Use a custom Jinja2 template file --batch {milestones,tags} Run loghub for all milestones or all tags --no-prs Run loghub without any pull requests output --no-related-prs Do not display related prs on issues --no-related-issues Do not display related issues on prs

Label utility CLI arguments

loghub includes an additional utility to get or update labels.

usage: loghub-labels [-h] [-u USERNAME] [-p PASSWORD] [-t TOKEN]
                        [-a [{get,update}]] [-f FILENAME]
                        repository
positional arguments:     repository            Repository name to generate the Changelog for, in the                         form user/repo or org/repo (e.g. spyder-ide/spyder)
optional arguments:     -h, --help                                     show this help message and exit
-u USERNAME, --username USERNAME                         Github user name
-p PASSWORD, --password PASSWORD                         Github user password
-t TOKEN, --token TOKEN                         Github access token
-a [{get,update}], --action [{get,update}]                         Action to take
-f FILENAME, --filename FILENAME                         File for storing labels