Git Product home page Git Product logo

github-tools / github-release-notes Goto Github PK

View Code? Open in Web Editor NEW
879.0 879.0 331.0 3.93 MB

Node module to create a release or a changelog from a tag and uses issues or commits to creating the release notes.

Home Page: https://github-tools.github.io/github-release-notes/

License: GNU General Public License v3.0

JavaScript 100.00%
changelog github-releases gren release release-automation release-notes

github-release-notes's Introduction

gren πŸ€–

Github release notes and changelog generator

npm version Build Status Join the chat at https://gitter.im/github-release-notes/Lobby Codecov npm downloads Automated Release Notes by gren

All Contributors

OK, what can gren do for me?

gren is a small helpful robot that will do for you just create a release from a tag and compile the release notes using issues or commits.

It also can generate a CHANGELOG.md file based on the release notes (or generate a brand new).

The Motivation and Concept

Everyone loves neat, transparent, informative release notes. Everyone would also rather avoid maintaining them. What a hassle to have to evaluate what issues have been solved between two points in project's timeline, what types of problems they were, are they important to inform the users about, what issues solved them, etc.

Wouldn't it be great to get fantastic release notes compiled for you automatically based on all the hard work you put into your GitHub issues and pull requests?

The main motivation for bringing gren to life was the need for auto-generating release notes for every tag in a project. The process, as explained here, requires the tagger to go to your project's releases page in GitHub, draft that tag as a new release and manually add what has changed.

Let gren take care of that for you. It automates this process and also writes release notes for you, creating something like this:

v0.6.0 (14/03/2017)

Framework Enhancements:

  • #32 Unwrap github-api promises
  • #26 Use external config file
  • #23 Introduce templates for the issues
  • #19 Add an "ignore label" flag
  • #12 Add the chance to rebuild the history of release notes

Bug Fixes:

  • #29 Remove escaping character on regex
  • #24 The changelog action doesn't compile latest release

(yes, this is one of πŸ€– 's actual releases)

Feed gren πŸ€–

Where is the data coming from? There are two options:

issues (⭐)

If you manage your project with issues, that's where all the information about a change are. Issue labels increase the level of depth of what the release notes should show, helping gren to group the notes.

e.g. if you see the example above, the issues are grouped by the two labels enhancement and bug, then customised via a config file.

gren generates those notes by collecting all the issues closed between a tag (defaults to latest) and the tag before it (or a tag that you specify). If you want to be more accurate on the issues that belong to a release, you can group them in milestones and use only the issues that belong to that Milestone.

The output above is a result of release notes built from issues.

Help πŸ€– to write wonderful stuff (issues)

In order to have splendidly generated release notes, we recommend to follow these conventions:

  1. Start the title with a verb (e.g. Change header styles)
  2. Use the imperative mood in the title (e.g. Fix, not Fixed or Fixes header styles)
  3. Use labels wisely and assign one label per issue. gren has the option to ignore issues that have one of the specified labels.

commits

The simplest way of getting data is from the commits you write. Even though it doesn't require a machine-readable commit, it is still better to have them in a nice format.

The output then uses commit messages (title + description) to look something like:

v0.9.0 (17/05/2017)

  • Filter milestones (#75)
    • Create milestones data-source option
    • Add documentation for the milestones option
  • Support GitHub enterprise (#73)
    • Support GitHub enterprise
    • Add api-url to options documentation
  • Update CHANGELOG.md

Help πŸ€– to write wonderful stuff (commits)

In order to have splendidly generated release notes, we recommend to follow these conventions:

  1. Start the subject line with a verb (e.g. Change header styles)
  2. Use the imperative mood in the subject line (e.g. Fix, not Fixed or Fixes header styles)
  3. Limit the subject line to about 50 characters
  4. Do not end the subject line with a period
  5. Separate subject from body with a blank line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why not how

Installation

Install github-release-notes via npm:

npm install github-release-notes -g

Setup

First, generate a GitHub token, with repo scope, at this link. Then add this line to ~/.bash_profile (or ~/.zshrc):

export GREN_GITHUB_TOKEN=your_token_here

Show the internet that you use gren for automating your release notes -> Automated Release Notes by gren

[![Automated Release Notes by gren](https://img.shields.io/badge/%F0%9F%A4%96-release%20notes-00B2EE.svg)](https://github-tools.github.io/github-release-notes/)

Basic Usage

gren gets the repo information directly from the folder where git is initialised.

# Navigate to your project directory
cd ~/Path/to/repo
# Run the task (see below)
gren release

Otherwise, you can run it anywhere passing the repo information:

gren release --username=[username] --repo=[repo name]

If you don't want to save the token, you can specify one as an option:

gren release --token=[your token]

Commands

There are two main commands that can be ran with πŸ€–:

gren release

gren will look for the latest tag, draft a new release using the issues closed between when that tag and the one before were created and publish that release in your release panel in your GitHub repo. (@see how to feed πŸ€–).

gren changelog

Create a CHANGELOG.md file using all the release notes of the repo (like the ones generated by πŸ€– ). If the file exists already, use the --override option to proceed.

gren changelog --override

To generate a brand new release notes, using the same approach as per the releases, you have to run the command with the --generate option.

gren changelog --generate

Help! πŸ†˜

gren is using Commander.js which generates the --help section. To trigger the help of a command, run:

# General usage
gren --help
# Command usage
gren help release # or gren release --help

It's also possible to see all the examples here or directly in the terminal:

gren examples release

Configuration file

You can create a configuration file where the task will be run to specify your options. See how to set up the config file The accepted file extensions are the following:

  • .grenrc
  • .grenrc.json
  • .grenrc.yml
  • .grenrc.yaml
  • .grenrc.js

Init

If you need help to create the configuration file, you can run the following command and follow the instructions

gren init

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Dan Klausner

πŸ› πŸ’»

David Sevilla MartΓ­n

πŸ“–

Alexander Vassbotn RΓΈyne-Helgesen

πŸ› πŸ’»

Joaquin Corchero

πŸ’»

David Parker

πŸ’»

Mario Tacke

πŸ’»

Kevin Yeh

πŸ’»

Jack O'Connor

πŸ’»

Keith Stolte

πŸ“– 🎨

David Poindexter

πŸ“–

Frank S. Thomas

πŸ’»

pawk

πŸ’»

Yang, Bo

πŸ’»

Victor Martinez

πŸ“–

Tyler Hogan

πŸ’»

Blair Gemmer

πŸ“–

Han

πŸ’»

donmahallem

πŸ’»

Ahmed

πŸ’»

MΓ΄nica Ribeiro

πŸ’»

Tanya Bushenyova

πŸ’»

This project follows the all-contributors specification. Contributions of any kind welcome!

github-release-notes's People

Contributors

aelbozie avatar alexcanessa avatar allcontributors[bot] avatar atry avatar blairg23 avatar cjbarth avatar dependabot[bot] avatar donmahallem avatar flavienbusseuil avatar fthomas avatar gitter-badger avatar harikrishnanbalagopal avatar jackocnr avatar joaquincorcherofmp avatar kstolte avatar kyeah avatar lianghx-319 avatar mariotacke avatar monicaribeiro avatar pachirel avatar pawk avatar tybot204 avatar v1v avatar viatrix avatar welldan28 avatar yogevbd avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

github-release-notes's Issues

Introduce templates for the issues

Give the opportunity to set a custom template for the issues in the options (maybe in a .grenrc file).

The reason is that I might want to output different types of information from the issue.

It could be something like:

templates: {
    issue: '{{labels}} {{text}} {{link}}'
}

Rework the Changelog generator function

The changelog action now has some --override capacity which is not really needed.

What the changelog function should be responsible for should only be to update the current CHANGELOG.md using the existing releases.

  • The --override flag should only be able to override the latest release or a specific tag range.
  • Use the --tags=[] option to configure the release range too. optional
  • Would the changelog action be able to create release notes or should it just be based on the existing ones?

Tag name in the options

Could be useful to have the tag name to release as an option. Default latest

The implementation would be at: (line 164)

tags.filter(function(tag, index) {
    return (index === 0 || tag.name === releaseTagName);
})

Migrate to ES2015

Since the module is getting bigger and bigger, would be easier to manage it if using ES2015 classes.

After this will be implemented we can also create more unit tests to improve the stability of the module.

Remove unused option user.name

There is an option user.name that, if not defined, makes everything crash.
Since we're not using that option at all, we can remove it and fix the issue.

This bug comes from #28

Installing old versions of github-release-notes no longer works

Hey guys.

I think recent changes may have broken older versions of github-release-notes

We were using 0.4.0, if I make a brand new package.json with

{
  "name": "blah",
  "version": "1.0.0",
  "devDependencies": {
    "github-release-notes": "0.4.0",
    "install": "^0.8.7",
    "npm": "^4.4.1"
  }
}

and then run npm install

It errors out with fatal: Authentication failed for 'https://github.com/alexcanessa/github.git/'

I'm guessing it's because this repo existed in the past but has since been moved to the github-tools org but older versions of github-release-notes don't know that. So; heads up that older versions are broken.

Updating to the latest version of github-release-notes fixed it for us. Don't know if you want to do anything more to mitigate this issue for other people.

Thanks for your time

Josh

Support pull requests without associated issues

Pull requests have all the discussion, tagging, search, project management, and other features of issues. But often, in a gren-enabled project, I'm still forced to create a separate issue when I've already made the PR that would close it (e.g. for a previously-unreported problem) because otherwise, the release notes would be incomplete. This adds overhead to what can be a seamless GitHub workflow.

The solution: I think gren should treat merged PRs as their own, self-closing issues if they don't explicitly close any other issue.

Add the chance to rebuild the history of release notes

Have the flag for history releases or latest (default).

If history:

  • check all the release, and create the body for all of them.
  • create the full changelog
  • if the changelog or the release body already exist, stop.
  • if the option override is true, then override both changelog and release notes

Use milestones to create release notes

Give the option to:

  1. List only issues that have Milestones, which I imagine would be just an option:
{
    "onlyMilestones": true
}
  1. Create release notes based on milestones rather then on dates. only applicable to issues
    To achieve it we need to create a matching system between the tag name and the milestone naming convention.
{
    "dataSource": "milestones",
    "milestoneMatch": "Release {{tag_name}}"
}
  1. Use the description of the milestone in the release body.
  2. Consider to filter only closed milestones (?)

Unwrap github-api promises

Stop using the callback from the github-api promises and handle the response through the promise itself, same as for catching the errors.

Use different files type for configuration

Would be nice to have the chance of having different type of files for configuration.

Right now only .json is allowed.

The script would look for:

  • .grenrc.json
  • .grenrc.yml
  • .grenrc.yaml
  • .grenrc.js
  • .grenrc

Include various types of commit messages

It would be useful to include options eg.

  • --Include=All
  • --Include=Commits
  • --Include=MergePull

to return for example merge pull request commit messages at the moment it only returns commit messages

image

README doesn't explain what gren does

Installed gren, created github key, ran gren, no errors... but nothing seems to have happened?

gren --help yields nothing useful.

What exactly is the expected result of all this? README seems to miss the mark in terms of explaining what this (hopefully useful) tool does, I'm afraid.

FWIW, my console output:


kieffer@MacBook-Pro-3$ pwd
/Users/kieffer/projects/node-mime

kieffer@MacBook-Pro-3$ lsf
total 80
-rw-r--r--   1 kieffer  staff  1098 May 11 21:53 LICENSE
-rw-r--r--   1 kieffer  staff  1894 Sep 12 15:32 Mime.js
-rw-r--r--   1 kieffer  staff  5053 Sep 12 15:40 README.md
-rw-r--r--   1 kieffer  staff   150 Sep 12 15:32 cli.js
-rw-r--r--   1 kieffer  staff   114 Sep 12 15:32 index.js
-rw-r--r--   1 kieffer  staff    88 Sep 12 15:32 lite.js
drwxr-xr-x  35 kieffer  staff  1190 Sep 12 15:44 node_modules/
-rw-r--r--   1 kieffer  staff  8168 Sep 12 15:44 package-lock.json
-rw-r--r--   1 kieffer  staff   962 Sep 12 15:44 package.json
drwxr-xr-x   6 kieffer  staff   204 Sep 12 15:40 src/
drwxr-xr-x   4 kieffer  staff   136 Sep 12 15:32 types/

kieffer@MacBook-Pro-3$ gren

Release task:
===================================
Getting the list of releases: ..... (0.49 secs)
1 releases found
Getting tags: .... (0.33 secs)
Tags found: v1.4.0, v1.3.6
Getting the tag dates ranges: .... (0.34 secs)
Creating the body blocks from releases:
Getting all closed issues: ...... (0.52 secs)
13 issues found
Skipping v1.4.0 (use --override to replace it)

kieffer@MacBook-Pro-3$ lsf
total 80
-rw-r--r--   1 kieffer  staff  1098 May 11 21:53 LICENSE
-rw-r--r--   1 kieffer  staff  1894 Sep 12 15:32 Mime.js
-rw-r--r--   1 kieffer  staff  5053 Sep 12 15:40 README.md
-rw-r--r--   1 kieffer  staff   150 Sep 12 15:32 cli.js
-rw-r--r--   1 kieffer  staff   114 Sep 12 15:32 index.js
-rw-r--r--   1 kieffer  staff    88 Sep 12 15:32 lite.js
drwxr-xr-x  35 kieffer  staff  1190 Sep 12 15:44 node_modules/
-rw-r--r--   1 kieffer  staff  8168 Sep 12 15:44 package-lock.json
-rw-r--r--   1 kieffer  staff   962 Sep 12 15:44 package.json
drwxr-xr-x   6 kieffer  staff   204 Sep 12 15:40 src/
drwxr-xr-x   4 kieffer  staff   136 Sep 12 15:32 types/

kieffer@MacBook-Pro-3$

Fix object-deep-assign bug

Since not part of dependencies, object-deep-assign is undefined.

[Error: Cannot find module 'object-assign-deep']

Create a --help section

Would be nice to have the options listed with the description when there is the --help flag.

Check if there are no tags

Manage the case where there are no tags in the repo.

Currently:

Getting the list of releases: ....... (0.64 secs)
0 releases found
Getting tags: .... (0.33 secs)
Tags found:
Getting the tag dates ranges: . (0.00 secs)
Creating the body blocks from releases:
Getting all closed issues: .
Task(s) stopped because of the following error:
TypeError: Cannot read property '1' of undefined

Add tests

Create unit tests for utils and gren functions

Remove the releases limit

Apparently there is a bug which stops the script to run more than 30 releases. It might be a pagination thing coming from the APIs.

Needs further investigation.

Check the network

Check the network before starting the task, and fail if there is no network

Error when there is only one tag

If I try to run the script on repos with one tag only, I get this error:

Task(s) stopped because of the following error:
TypeError: Cannot read property 'name' of undefined

Allow functions as template values

Since we have now a .grenrc.js file, is possible to pass functions to the template configuration.
We can update the code so to accept a function and use it to parse the informations.

This way the user can customise the output with JavaScript (e.g. date formatting #27)

Cleanse option

Allow to --cleanse, so to delete all the tags between the latest tag (the new release) and the latest release.

Expanded options for commit template variables

Unless I'm mistaken it seems message is the only variable available for templating commit entries. I was hoping to put together a changelog with a format something like:

[{{sha}}]({{url}}) {{message}} - {{author.name}}

I was wondering if there's a specific reason why commitMessages() just pulls out the commit message rather retaining the commit object (or a subset of it), which can then pass through the system eventually allowing generateCommitsBody() to template on more than just the commit message? If not, is this something that could be added?

Specify which tag to build

I want to have the chance to build the release of a specific tag, e.g. --tags=0.1.0.
This would create the release notes based on the tag 0.1.0 and the previous one.

I also want to specify the range between two tags, so --tags=2.0.0,1.0.0 would create the release notes with all the issues closed between those two tags.

Fix multiple repo information

When giving all the repo information the task fails with:

[TypeError: Cannot assign to read only property '0' of [object String]]

Issue coming from #28

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.