rcmachado / changelog Goto Github PK
View Code? Open in Web Editor NEWRead, validate and manipulate CHANGELOG.md files that follow keepachangelog.com specification
License: MIT License
Read, validate and manipulate CHANGELOG.md files that follow keepachangelog.com specification
License: MIT License
Add a lint
command that could educate about best practices regarding changelog messages. One easy win would be checking for Add ...
, Fix ...
, Remove ...
kind of messages in their respective sections.
Some examples:
Add some interesting feature
messages under Added
section became Some interesting feature
(since Added
section already denotes it was added)Fixed issue that prevents something
message under Fixed
section became Issue that prevents something
Other issues it could check:
As now we have an official Docker image, we can easily have a GitHub Action.
The action can be used to:
fmt
)release
)There are some tools that we could use to monitor the code quality in during the continuous integration process.
One of them is https://goreportcard.com/: it runs tools to diagnose the code (got vet
, go fmt
, etc) and compare the results with the best practices.
The fmt
command formats and normalizes the changelog file.
But to check if the file is formatted correctly, we need to run something similar to:
diff -u <(changelog fmt -f CHANGELOG.md) CHANGELOG.md
We can simplify this code to:
changelog fmt --check
Which is useful specially for CI environments.
Command: release
Version: 0.4.1
When trying to call release
command it fails if we have a link but not the corresponding version in file.
panic: runtime error: index out of range [1] with length 0
goroutine 1 [running]:
github.com/rcmachado/changelog/chg.(*Changelog).Release(0xc000096c30, 0x7ffd5b806c9f, 0x5, 0xc0000206e0, 0xa, 0x0, 0x0, 0x0, 0x0, 0x0, ...)
/go/src/github.com/rcmachado/changelog/chg/changelog.go:107 +0x689
github.com/rcmachado/changelog/cmd.newReleaseCmd.func1(0xc0000c5180, 0xc0000aa230, 0x1, 0x5, 0x0, 0x0)
/go/src/github.com/rcmachado/changelog/cmd/release.go:40 +0x198
github.com/spf13/cobra.(*Command).execute(0xc0000c5180, 0xc0000aa1e0, 0x5, 0x5, 0xc0000c5180, 0xc0000aa1e0)
/go/pkg/mod/github.com/spf13/[email protected]/command.go:826 +0x460
github.com/spf13/cobra.(*Command).ExecuteC(0x7abf20, 0x43b60a, 0x797340, 0xc000000180)
/go/pkg/mod/github.com/spf13/[email protected]/command.go:914 +0x2fb
github.com/spf13/cobra.(*Command).Execute(...)
/go/pkg/mod/github.com/spf13/[email protected]/command.go:864
github.com/rcmachado/changelog/cmd.Execute()
/go/src/github.com/rcmachado/changelog/cmd/root.go:83 +0x31
main.main()
/go/src/github.com/rcmachado/changelog/main.go:6 +0x20
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased]
### Changed
- Do not exclude outliers when predicting.
- Adjusting CPU/memory for the endpoint.
- Configured Redis.
[Unreleased]: https://github.com/org/repo/compare/0.2.0...HEAD
[0.2.0]: https://github.com/org/repo/compare/0.1.0...0.2.0
A nice addition to changelog
command is the ability to manipulate changelog entries. More specifically, adding entries under Unreleased
version programmatically.
For example:
$ changelog added "Your nice change"
Would add Your nice change
under Added
section of Unreleased
version.
Possible commands:
added
changed
deprecated
fixed
removed
security
When running the changelog
command we can detect and build the compare URL based on previous versions already specified in the markdown file.
But if we have a brand new .md
with only an Unreleased
section, the detection becomes unreliable and we require the user to pass --compare-url
flag. If we are operating in a git checkout, we can automatically detect it based on the remote configuration.
The goal is to implement this for GitHub repositories in the first place.
Calling it release
feels better than bump
.
Given following malformed changelog:
$ cat CHANGELOG.md
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.4.0] - 2020-08-31
### Changed
- e2e: Updated used sonobuoy version to v0.19.0.
- e2e/local-testing: use Terraform 0.13.
- Default Kubernetes version is now v1.19.0.
- As upstream Kubernetes deprecated hyperkube image, now each controlplane component
use individual images. As upstream does not publish kubelet images yet, new default kubelet image
is build from [kubelet](https://github.com/flexkube/kubelet) repository and available for pulling
from `quay.io/flexkube/kubelet` registry.
- controlplane: static kube-apiserver now runs on host network and with `--permit-port-sharing=true`
flag set to make use of binding with SO_REUSEPORT option, which eliminates the need of bootstrap
HAProxy and HAProxy container on self-hosted kube-apiserver pods.
- e2e: use Helm v3.3.0.
- Updated Go dependencies to latest versions.
### Removed
- e2e: Remove bootstrap API Load Balancer - it is no longer needed as since Kubernetes v1.19.0,
kube-apiserver is able to bind with SO_REUSEPORT, if `--permit-port-sharing=true` flag is set.
## [0.3.3] - 2020-08-29
changelog
panics with the following error:
$ changelog fmt
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x10 pc=0x52e763]
goroutine 1 [running]:
github.com/rcmachado/changelog/parser.(*renderer).ListItem(0xc000022720, 0x6635c0, 0xc00007cd50, 0xc0001883c0, 0x1, 0x1)
/home/invidian/go/pkg/mod/github.com/rcmachado/[email protected]/parser/parser.go:189 +0x143
github.com/rcmachado/changelog/parser.(*renderer).RenderNode(0xc000022720, 0x6635c0, 0xc00007cd50, 0xc0001883c0, 0xc00012a601, 0x0)
/home/invidian/go/pkg/mod/github.com/rcmachado/[email protected]/parser/parser.go:84 +0xe5
github.com/russross/blackfriday/v2.Run.func1(0xc0001883c0, 0x40ea01, 0x0)
/home/invidian/go/pkg/mod/github.com/russross/blackfriday/[email protected]/markdown.go:392 +0x5a
github.com/russross/blackfriday/v2.(*Node).Walk(0xc00012a640, 0xc000151c00)
/home/invidian/go/pkg/mod/github.com/russross/blackfriday/[email protected]/node.go:284 +0x63
github.com/russross/blackfriday/v2.Run(0xc00013c000, 0x52c, 0xe00, 0xc000151cb0, 0x2, 0x2, 0x0, 0x0, 0x0)
/home/invidian/go/pkg/mod/github.com/russross/blackfriday/[email protected]/markdown.go:391 +0x26d
github.com/rcmachado/changelog/parser.Parse(0x663580, 0xc0000226c0, 0x0)
/home/invidian/go/pkg/mod/github.com/rcmachado/[email protected]/parser/parser.go:26 +0x1e5
github.com/rcmachado/changelog/cmd.newFmtCmd.func1(0xc0001702c0, 0x7be188, 0x0, 0x0)
/home/invidian/go/pkg/mod/github.com/rcmachado/[email protected]/cmd/fmt.go:14 +0x3b
github.com/spf13/cobra.(*Command).execute(0xc0001702c0, 0x7be188, 0x0, 0x0, 0xc0001702c0, 0x7be188)
/home/invidian/go/pkg/mod/github.com/spf13/[email protected]/command.go:846 +0x2c2
github.com/spf13/cobra.(*Command).ExecuteC(0x789440, 0x44536a, 0x7735a0, 0xc000000180)
/home/invidian/go/pkg/mod/github.com/spf13/[email protected]/command.go:950 +0x375
github.com/spf13/cobra.(*Command).Execute(...)
/home/invidian/go/pkg/mod/github.com/spf13/[email protected]/command.go:887
github.com/rcmachado/changelog/cmd.Execute()
/home/invidian/go/pkg/mod/github.com/rcmachado/[email protected]/cmd/root.go:84 +0x31
main.main()
/home/invidian/go/pkg/mod/github.com/rcmachado/[email protected]/main.go:6 +0x25
Implement a command to create the initial Changelog structure. Something like:
changelog init
Then it would create a CHANGELOG.md file containing the base structure.
Add an option to show only the compare URL for a given version. For example:
$ changelog show 1.2.3 --only-compare-url
https://example.com/compare/1.2.2..1.2.3
People make mistakes:
## Changed
- This will be discarded
As the sections are limited, we should be able to recognize it and properly parse this.
Run gometalinter automatically on CI server.
This is the same tool run by Go Report Card.
Would be nice to have this as a Make task, so we can easily run it locally too.
Add a changelog bump 1.2.3
command that will:
Unreleased
to 1.2.3
Unreleased
sectionFor the compare link, we could add an option (--version-link
) or infer from an existing version.
When we have duplicated sections:
### Added
- Item 1
### Added
- Item 2
The "Item 2" is lost - it should be merged within the same section as "Item 1".
Add documentation (preferably with a link) on how to easily download the compiled binary from GitHub releases.
Details can be found at https://help.github.com/en/github/administering-a-repository/linking-to-releases
We don't have any way to manage/vendorize the dependencies used in the project (currently, only blackfriday v2).
We should investigate the use of dep (at least until vgo is not ready for prime time).
When bumping a version, we could easily check if this version already exists and throw an error when releasing.
Maybe a -f/--force
option could be given to proceed anyway.
The commands under cmd
directory (release
, fmt
, etc.) don't have tests.
The should be tested, as the rest of the code are.
bundle
fmt
release
show
commands.go
(added
, changed
, etc)People make mistakes when build change logs manually. One most common is adding more (or fewer) header markers than necessary. For example:
#### Fixed
- Item 1
- Item 2
Currently, as this don't match the spec, changelog
will just discard the whole section.
Assuming the second heading will be the version, we don't need to explicitly parse for semver format - we could just decompose it into its components (version
, date
and yanked
).
To make it easier for who just wants to download a binary from GitHub and use the tool, we need to:
* Note that CircleCI doesn't support macOS builds in free plan, so we probably need to evaluate something else.
The .tar.gz
archives are not being generated when a release is created because of the following configuration:
Lines 3 to 6 in d4dd522
This breaks scripts that were relying on them (eg. https://app.circleci.com/pipelines/github/scanapi/scanapi/268/workflows/c27be05e-0bd8-4d07-b143-b48bec5312f0/jobs/548/steps).
We need to fix the configuration so archives are generated again.
Document properly how to release a new version.
Currently the process is:
A GitHub release will be automatically created.
It would be nice to have an interactive mode, where just typing changelog
would bring a menu with options:
$ changelog
Choose an option
1. Initialize a new file
2. New entry
3. Format file
4. (...)
Enter an option [1-4]:
It should have the same effect as calling the command passing the proper options directly in the command line.
Investigate what of the following styles would be preferred when rendering the changelog:
- A really long line without any kind of hard break or limit to its length
- A line that will break at 72 and
indent the second line with 2 chars
For parsing, it shouldn't matter.
In a scenario where you migrate the project from one repository provider to another (eg. Bitbucket to GitHub) or even renaming the project, would be nice to automatically change the compare links for each version. Something like:
$ changelog fmt --compare-url "https://example.com/{{.PreviousVersion}}-{{.CurrentVersion}}"
This would reformat the changelog file, updating all the compare URLs using the new template.
(Stolen from olivierlacan/keep-a-changelog#249)
Internally, changelog
current has the following structs:
Changelog
: the whole changelog dataVersion
: represents each versionChangeType
: Added
, Changed
, etc.ChangeList
: messages for a given "section" (eg. Added).Item
: each messageSome of the structs have pretty obvious names (like Version
) but others (like ChangeList
) could benefit of some more thinking.
goreleaser creates a changelog using commits.
It should use a proper changelog for it (maybe even changelog show $CIRCLE_TAG
)
Some tests are already using https://github.com/stretchr/testify library to assert test results, but other still do if result != expected { ... }
.
Assert library although not essential, provides a better experience while developing. So the idea is to normalize all the tests to use it.
We shouldn't fail test steps if COVERALLS_TOKEN
is missing (which happens in forks).
See #58.
We should gracefully detect this or at least don't fail the tests
job.
As now we have a proper docker image published in Docker Hub (https://hub.docker.com/r/rcmachado/changelog), it's worth mentioning it in the documentation along with instructions on how to use it.
Currently our documentation is very basic - only the README - and doesn't cover all commands nor provide much examples.
We need to improve this so it's easier for someone who wants to use the tool. The docs could have:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.