miniscruff / changie Goto Github PK

https://changie.dev/guide/upgrade/ looks bad on the guide page https://changie.dev/guide/ as it has no header.

Should be in the CONTRIBUTING file to match other Github options.

Update contributing guide to reference template

I think dependabot works for go modules, if not find something that will work.

In order to support the ## v1.0 - 2020-12-31 format, we need to know the current date and potential time.

Since the only prefix versions can have is a 'v' anyway, instead of allowing any string in the --remove-prefix argument, just use a boolean.

probably use the same as the igloo repo, needs a badge on the readme to count

Is your feature request related to a problem? Please describe.
Is not a problem but can be useful a command changie next patch who echoes next version based on latest.

Describe the solution you'd like
Create a new command to echoes next release based on latest. (see additional context).

Describe alternatives you've considered
Add into batch command directly a conditional to check if "major", "minor" or "patch", get version using latest pipeline, then pass forward next version.

Additional context

Currently, it has parts of the readme and some features on it.
The features should be listed in the readme as well.
The website does not need the readme badges either.

If the changie latest command is run in a project that contains no versions, the command panics.

reproduction:

tmp=$(mktemp -d) && cd $tmp && changie init && changie latest; rm -rf $tmp

panic: runtime error: index out of range [0] with length 0

goroutine 1 [running]:
github.com/miniscruff/changie/cmd.latestPipeline(0x7bb040, 0x9a74d0, 0x74f6ab, 0x4, 0x74f64b, 0x4)
	/home/user/src/go/src/github.com/miniscruff/changie/cmd/latest.go:84 +0x785
github.com/miniscruff/changie/cmd.runLatest(0x971600, 0x9a74d0, 0x0, 0x0, 0x0, 0x0)
	/home/user/src/go/src/github.com/miniscruff/changie/cmd/latest.go:40 +0x3d
github.com/spf13/cobra.(*Command).execute(0x971600, 0x9a74d0, 0x0, 0x0, 0x971600, 0x9a74d0)
	/home/user/src/go/src/github.com/spf13/cobra/command.go:850 +0x47c
github.com/spf13/cobra.(*Command).ExecuteC(0x971de0, 0x74f1a1, 0x1, 0x74f410)
	/home/user/src/go/src/github.com/spf13/cobra/command.go:958 +0x375
github.com/spf13/cobra.(*Command).Execute(...)
	/home/user/src/go/src/github.com/spf13/cobra/command.go:895
github.com/miniscruff/changie/cmd.Execute(...)
	/home/user/src/go/src/github.com/miniscruff/changie/cmd/root.go:19
main.main()
	/home/user/src/go/src/github.com/miniscruff/changie/main.go:14 +0x9d

changie init will begin the process of initializing changie. The basic components are a "change" folder with a simple default. Add a basic template to the folder. Include a header template file. Create a changelog file with the basic template and "empty" release.

• Probably use Go as static site generator
• Find a good theme
• Move documentation from readme to new docs
• Create tasks for working with docs

When preparing a new release we will need a new changelog file from our combined changes. changie generate with a required parameter of the new version.

Seems only natural to include the changelog as part of the documentation for a tool that creates changelogs.

Update contributing guide to reference template

Problem and Use Case

At the moment, the body of a changelog entry cannot contain any newlines.
If you use "Upgrade Notice" or "Deprecated" kinds in your changelog, it is ofter required to write more than one sentence.
As Markdown (and YAML) allows line breaks in list items if they are indented correctly, Changie should also support such entries.

Suggestion

The body prompt for a new entry should be modified so a newline character is not interpreted as the end of the entry.
A specific character sequence (EOF or a dot) can be used instead of the newline character.

The resulting YAML file might look as follows:

kind: Removal
body: |
  This is the first,
  and this the second line!

https://goreleaser.com/customization/announce/

I just gave this tool a try for the first time, and the first command I ran was changie init. The command failed with the following

$ changie init   
Error: mkdir changes/unreleased: permission denied

$ ls -ld ./changes
drw-r--r-- 2 user group 4096 Dec 28 12:46 ./changes

I can see that the wrong permissions are being used to create the non-existent directory (0644 instead of 0755)
3737ce6#diff-345cd3beb7d905a8bef99d83e99c62678bfd5101a26d30104ecc9320602072acR70

It is likely that this bug is not being caught because the tests use an in-memory afero filesystem which may not exercise the limits of the filesystem permissions.

This will probably need to be backward incompatible but it would be nice to allow for formatting and choices per kind.

Instead of:
kinds: [string of each kind]

It should be:

kinds:
  - label: prompt label
    header: header separate from label
  - repeat

Configurations at the top level are default to all kinds with the option to extend or override the defaults per kind.

Will complain if the maintainer is empty

https://opensource.guide/starting-a-project/#writing-a-readme

Cobra supports auto completion, we should provide the command and docs on how to add changie auto completion to your environment.

https://github.com/spf13/cobra/blob/master/shell_completions.md

promptui has a select and prompt feature but that is all.

https://github.com/AlecAivazis/survey has many more prompt options such as mutliline, confirm and multiselect.
I think moving to survey is going to be better regardless as it is in more active development.

The selection of prompt tool should not dictate much in changie, a small abstraction should work and can reduce the testing overhead of using stdin strings for stuff.
(TODO design the above)

Maps are unordered and it is more common to see arrays of structs over a map in YAML files. Plus this will make testing consistent as arrays are ordered.

• required for docs page
• should be part of readme as a well
• not sure if its part of GitHub settings or anything, but if so do that too

Once all the other documentation tasks are done that way they can be tested live instead of building a new release.

Update contributing guide to reference template

At least as a trial run to see if there are benefits to having one created.

From goreleaser docs:

  # If set, will create a release discussion in the category specified.
  #
  # Warning: do not use categories in the 'Announcement' format.
  #  Check https://github.com/goreleaser/goreleaser/issues/2304 for more info.
  #
  # Default is empty.
  discussion_category_name: General

For category name use "Release"

In addition to storing custom fields, we will need to be able to customize how our change blocks are rendered. Probably an option in our config file.

A small bit of self-promoting in the default header. Can easily be changed.

Golang has a great linting tool but with other files in the project like yaml, markdown and so on we should lint all of them at once.
https://github.com/github/super-linter is a good option.

With all the configuration options it would be nice to have a few examples, probably an examples directory and a page on the website listing them all.

https://goreportcard.com/

Could check for min length, max length, or any other string check we allow in the custom choices.

When creating new releases in GitHub ( and probably other tools ) you can add release notes directly to the release. This is probably identical or very similar to the generated output of changie. It would be very convenient if there was some connection between a GitHub release and a changie output. Maybe a GitHub action?

Afero is used as a file abstraction in order for us to write tests, but writing tests with a temp directory is very easy so we should do that instead.

https://tip.golang.org/pkg/io/fs/
https://golang.org/pkg/testing/fstest/#MapFS to test

• Remove afero as a dependency
• Create interfaces for writing files as fs.FS does not include writing details. os has functions to write files though.
• Create a struct to handle mocking writes for tests to extend the memfs but with write interfaces.

• generate config from passed in or default config values
• should be a yaml file at the project root

• Hidden CLI command to generate CLI docs
• Add to CI

Use a custom domain ( already purchased ) for website

Starting with:

• Go + goreleaser
• Package.json

Originally posted by @miniscruff in #98 (comment)

Update contributing guide to reference template

A simple cli prompt to generate new "change" files. Should store for now the date, time and body of a change. More will come later.

The theme used does not provide "Edit" or "Report" issues on pages, but it should not be too hard to include a footer or header to add links.

Add option for component headers.

So instead of:
header > kind > fragment

It can be:
header > component* > kind* > fragment
where both component and kinds are optional

Problem and Use Case

The changelog keeps track of changes you made to your project and should help end-users and developers to understand which new features or breaking changes were introduced.
Changie combines different descriptions of changes together which will result in an overview for specific releases (tags).
Nevertheless it is sometimes a good idea, to describe your release/version in a few sentences so it is easier for other people to get an overview what the purpose of a release is without reading all specific changes.

Example:

## v1.2.3 (2021-04-05)

This release bundles a lot of new logging handler endpoints and an internal rework of the underlying log handling,
so it is recommended to check if another handler might able to increase the performance of your app.
[and a few sentences more]

### Added
- ...

### Fixed
- ...

Suggestion

One should be able to add an optional snippet/header if a new batch is created from unreleased fragments.
This might be implemented by providing a command line option which accepts a path to a file.
An interactive prompt is also a valuable option for short preambles.

Example Snippet:

This release bundles a lot of new logging handler endpoints and an internal rework of the underlying log handling,
so it is recommended to check if another handler might able to increase the performance of your app.
[and a few sentences more]

Changie CMD:

changie batch 1.2.3 --preamble path/to/file.md

Updating the changelog file acts as the point of "this is a now a new version" but many projects have version fields in other places that should update at the same time. Some examples are package.json for javascript, setup.py for python packages, sphinx packages have a version value, etc. Goreleaser allows using ldflags as build parameters which can be injected from changie latest.

Configuration:

replacements:
- path: file/path.ext
  find: '  "version": ".*",' # regex search each line in file
  replace: '  "version": "{{.VersionNoPrefix}}",' # go template line replacement

For a javascript package.json:

{
  "name": "test-project",
  "version": "1.0.0",
  "description": "changie project",
  "main": "src/main.js",
}

Replace Struct:

type ReplaceData struct {
    Version string  // original version
    VersionNoPrefix string // no v prefix if version had it
}

When developing a project what aspects of changes are important will vary, therefore we should create a system to store and template custom fields.