rcmachado / changelog Goto Github PK

Track and report test coverage.

Codecov and Coveralls are two options to report it.

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)

To make it easier for who just wants to download a binary from GitHub and use the tool, we need to:

• Build in macOS*
• Build in Linux
• Upload to GitHub Releases

* Note that CircleCI doesn't support macOS builds in free plan, so we probably need to evaluate something else.

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.

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.

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.

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 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

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.

Internally, changelog current has the following structs:

• Changelog: the whole changelog data
• Version: represents each version
• ChangeType: Added, Changed, etc.
• ChangeList: messages for a given "section" (eg. Added).
• Item: each message

Some of the structs have pretty obvious names (like Version) but others (like ChangeList) could benefit of some more thinking.

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.

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).

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.

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".

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).

People make mistakes:

## Changed
- This will be discarded

As the sections are limited, we should be able to recognize it and properly parse this.

Add a changelog bump 1.2.3 command that will:

• Change Unreleased to 1.2.3
• Setup the correct compare link
• Add a new empty Unreleased section

For the compare link, we could add an option (--version-link) or infer from an existing version.

The .tar.gz archives are not being generated when a release is created because of the following configuration:

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.

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.

Calling it release feels better than bump.

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:

• Missing links for versions

goreleaser creates a changelog using commits.

It should use a proper changelog for it (maybe even changelog show $CIRCLE_TAG)

As now we have an official Docker image, we can easily have a GitHub Action.

The action can be used to:

• Ensure the CHANGELOG.md file is properly formatted (fmt)
• Prepare the changelog for release as part of a release process (release)

Command: release
Version: 0.4.1

What happens

When trying to call release command it fails if we have a link but not the corresponding version in file.

Stack trace

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 file

# 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

Document properly how to release a new version.

Currently the process is:

• Add a new version to CHANGELOG.md (could be done with the tool)
• Create a git tag

A GitHub release will be automatically created.

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:

• Explanation and examples for all commands
• Examples of specific uses - eg. prepare a release

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
• meta commands under commands.go (added, changed, etc)

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.

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

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.

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 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.

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.