From 1285189a580757561722a30ce23243f1b9ccacb7 Mon Sep 17 00:00:00 2001 From: Emiliano Leite Date: Tue, 23 Apr 2019 22:17:21 -0300 Subject: [PATCH 1/2] Update README --- README.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 5c4cefa..949839c 100644 --- a/README.md +++ b/README.md @@ -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 chagelogs. -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 @@ -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": @@ -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 ``` -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. @@ -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] ``` -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.(if these files are not deleted, 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] ``` + 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 @@ -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 From f5f5b002034a7b35fe9c816452784ee16a25de67 Mon Sep 17 00:00:00 2001 From: Emiliano Leite Date: Thu, 15 Apr 2021 20:56:22 -0300 Subject: [PATCH 2/2] Apply suggestions from code review --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 949839c..3d117ce 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![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 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 the loss of important release notes. @@ -96,7 +96,7 @@ Where the `VERSION` is mandatory and represents the number of the next version o 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 these files are not deleted, the same changes would appear 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: