This utility is written in Ruby. It uses the Octokit gem to:
- connect to Github
- retrieve the list of changes between 2 references
While 0.x versions were rather specific to the Polkadot repository, those limitations have been removed starting with 0.9.x versions.
The only requirement if you want to benefit from filtering labels in a better way that just comparing label names if to name your labels using the following generic pattern as see here:
<letter><number(s)>[-<arbitrary text>]
For instance:
B0-Silent 😎C1-Important ❗️Z12
Each of your issues or PR can have any number of labels. Advanced rules for labels can be defined and enforced using ruled_labels.
Running changelogerator will fetch all the changes for a given repository from Github. You should set a value for the ENV GITHUB_TOKEN if you want to avoid being rate limited.
The produce json will be formatted as:
{
"polkadot": {
"meta": { // top-level metadata which aggregates the info for .changes[].meta
"C": {
"min": 1,
"max": 3,
"count": 2
},
"D": {
"min": 2,
"max": 2,
"count": 1
}
},
"repository": {
/*
Includes the fields from the GitHub Repositories REST API.
See: https://docs.github.com/en/rest/repos/repos#get-a-repository
*/
},
"changes": [
/*
Each entry corresponds to a pull request with the fields from the
GitHub PR Rest API.
See: https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request
In addition to the API fields, each entry has a "meta" field with
information computed from its labels.
*/
{
"meta": {
"C": {
"C1": { // parsed from C1-needs_audit
"value": 1,
"text": "needs_audit"
},
"C3": { // parsed from C3-urgent
"value": 3,
"text": "urgent"
},
"agg": {
"min": 1, // related to the value 1 of C1
"max": 3, // related to the value 3 of C3
"count": 2 // two C-labels were parsed (C1 and C3)
}
},
"D": {
"D2": { // parsed from D2-runtime
"value": 2,
"text": "runtime"
},
"agg": {
"min": 2, // related to the value 2 of D2
"max": 2, // related to the value 2 of D2
"count": 1 // one D-label was parsed (D2)
}
}
}
// ... other fields from the REST API
}
]
}
}The produced json output can then easily reprocessed into a beautiful changelog using tools such as tera.
Some of the tests fetch data from GitHub. In case you do not have a
$GITHUB_TOKEN or simply do not wish to run them, set GITHUB_TOKEN=disabled
in your environment variables.
You can check out the tests to see it in action or query the help:
$ changelogerator --help
Changelogerator helps you generate a template friendly context made of the changes
between 2 references on your Github project.
Usage:
changelogerator [options]
-v, --[no-]verbose Run verbosely
-f, --from=FROM From Ref.
-t, --to=TO To Ref.
-p, --[no-]prefix Add (or not) a prefix for the repo
-h, --help Prints this help
The key point to generate a custom changelog is to slurp all the json you need into a single one that can then be passed as context to your favorite templating engine.
Here is an example:
jq \
--slurpfile foo.json \
--slurpfile bar.json \
-n '{
foo: $foo[0],
bar: $bar[0],
foobar: [
{ age: 12 },
{ name: "bob" }
] }' | tee context.json
- install:
bundle install - test:
rake test(some of the test appear to be UN responding for a good minute, see how to setGITHUB_TOKENabove to speed things up) - run single test:
ruby -I test test/test_with_token.rb -n test_polkadot_1_commit - linting/formatting:
rubocop