Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README #46

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update README #46

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1285189
Update README
emilianoLeite Apr 24, 2019
f5f5b00
Apply suggestions from code review
Apr 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 21 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@
[![Maintainability](https://api.codeclimate.com/v1/badges/6f5885536c6b5c82f304/maintainability)](https://codeclimate.com/github/codus/codelog/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/6f5885536c6b5c82f304/test_coverage)](https://codeclimate.com/github/codus/codelog/test_coverage)

A gem to help big teams to manage their chagelogs.
A gem to help big teams manage their changelogs.

When many people are developing changes to compose one product release, there can be some conflicts on merging the changes added to the Changelog. These conflicts can be badly resolved by git, which could cause lost of important release notes.
When many people are developing changes to compose one product release, there can be some conflicts on merging the changes added to the Changelog. These conflicts can be badly resolved by git, which could cause the loss of important release notes.

This gem provides a simple way to manage changelogs, avoiding these conflicts and missplaced informations. Changes are handled as if they were "migrations" and built when releasing a version, allowing a more precise knowledge of what changes were made to what version.
This gem provides a simple way to manage changelogs, avoiding these conflicts and missplaced informations. Changes are handled as if they were "migrations" and composed together when releasing a version, allowing a more precise knowledge of what changes were made in which version.

## Installation

Expand Down Expand Up @@ -39,9 +39,10 @@ After the installation run the following command to generate the `changelogs` fo
$ codelog setup
```

The `template.yml` file will be used to create a new change file. Change files from `unreleased` folder will compose the next release file when generated.
You should populate this template with the sections and topic examples desired for describe the current release that will be later added in the `CHANGELOG.md` file.
The template can be as the following example:
The `template.yml` file will be used to create a new change file. Change files from the `unreleased` folder will be composed into the next release file when a new release is generated.
You should populate this template with the sections and topic examples desired for describing the new release that will be later added into the `CHANGELOG.md` file.

The default template is as follows:

```yaml
"Added":
Expand Down Expand Up @@ -70,13 +71,13 @@ The template can be as the following example:

### Creating a new change file

After the initial setup every time a change is made, the developer should run the following command in the project root path:
After the initial setup, every time a change is made the developer should run the following command in the project root path:

``` bash
$ codelog new <NAME>
```

This will generate a change file, in `YAML` format, on `changelogs/unreleased/` from the `template.yml`, named with a timestamp value followed by the given `NAME`, converted to snake case, or the default name(`change`).
This will generate a change file (based on the `template.yml` file), in `YAML` format, in the `changelogs/unreleased/` folder, named with a timestamp value followed by the given `NAME`, converted to snake case, or the default name (`change`).

The new change file should be filled with information about the implemented change, all unused topics should be erased and the file committed.

Expand All @@ -86,23 +87,24 @@ Additionally, you can pass some extra options to the `new` command. Type `codelo

Once all changes were merged and the release is ready to be packed, all that must be done is to run the following command:

``` bash
```bash
$ codelog release [VERSION] <RELEASE_DATE>
```
Where the `VERSION` is mandatory and represents the number of the next version of the system. An additional parameter `RELEASE_DATE` can be used, and if so, the release date of the version will be that value. You can configure the format of this parameter in the configuration file, under `changelogs/codelog.yml`.

No conflicts to resolve. All changes documented.
Where the `VERSION` is mandatory and represents the number of the next version of the system. An additional parameter `RELEASE_DATE` can be used, and if so, the release date of the version will be that value. You can configure the format of this parameter in the configuration file, under `changelogs/codelog.yml`.

It will execute 3 steps:
This command will execute 3 steps:

- Generates a new release file at `changelogs/releases/` by merging all change files at `changelogs/unreleased/`
- Deletes the change files at `changelogs/unreleased/` because they now compose the new release. If it was not deleted, the change would appear repeated in the next release.
- Deletes the change files at `changelogs/unreleased/` because they now compose the new release.(Otherwise, the same changes would appear in the next release).
- Updates the `CHANGELOG.md` file by merging all the releases at `changelogs/releases/`.

If you don't want to specify the release version manually, you can use the `bump` command:

```bash
$ codelog bump [major|minor|patch] <RELEASE_DATE>
```

Where the first mandatory parameter is the desired release type, i.e: If you don't have any release, `codelog bump patch` will release the 0.0.1 version.

### Preview a Release
Expand All @@ -112,18 +114,21 @@ Sometimes, you just want to check the developed changes or preview how the next
``` bash
$ codelog release 1.0.0 --preview
```

Will display a preview of your changes on your console as if the version **1.0.0** has been released.

## Configuring

Since version 0.3.0, there are a few configurations that are possible. You can choose:
Since version `0.3.0`, there are a few configurations that are possible. You can choose:
- The name of the Changelog file.
- The header of the Changelog file.
- The format of the version and date on the releases.
- Whether to show the release date or not.
- The enter format for the release date.
- The input/output format for the release date.

To change these options, edit the `changelogs/codelog.yml` file.

In case you were using version 0.2.0, you will have to run:
In case you are using version `< 0.3.0`, you will have to run:

```bash
$ codelog setup
Expand Down