📝 Add Final Kata Description

Marius9595 · Marius9595 · commit 56a42998be2f · 2024-11-03T21:35:05.000Z
diff --git a/README.md b/README.md
@@ -1,86 +1,219 @@
-# changelog kata
+# Changelog kata
 
 ## Description
-This kata is about creating a changelog file for a project to track the changes 
-of a project automatically by versioning following [Semantic Versioning](https://semver.org/) and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). The changelog file should be in the format of [keepachangelog.com](https://keepachangelog.com/en/1.0.0/).
+This kata is about creating a **system that handles automatically, from commits, a changelog file** for a project to track the changes
+of it. This changelog file has to follow the format of [keepachangelog.com](https://keepachangelog.com/en/1.0.0/).
 
-## Requirements
+The system has to have the following **functionalities**:
+- Create a new changelog file with the first version of the project or unreleased changes.
+- Update the changelog file with new changes unreleased.
+- Create a new release with unreleased changes.
+- Update the changelog file with the new version and the changes of the new version aka new Release.
+- [Optional] Create the changelog file with all releases created.
 
-### Calculate next version from Release Candidate a Current Release
-A set of commits, since last Release, represents a Release Candidate.
 
-From the Release Candidate and Current Release, calculate the next version following [Semantic Versioning](https://semver.org/).
+The automation must be done following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and [Semantic Versioning](https://semver.org/).
 
-for example:
-```
-from Current Release v1.0.0
 
-Release Candidate:
-[
-    Commit{type: "feat", description: "add new feature"},
-    Commit{type: "fix", description: "fix bug"}
-]
+## keepachangelog
 
-calculateNextRelease(Release Candidate, Current Release) -> v1.1.0
-```
+This format has got different sections that will be explained in the following sections.
+
+### Header
 
-### Generate/Update changelog
-Using the release candidate and the current release, generate or update the changelog file in the format of [keepachangelog.com](https://keepachangelog.com/en/1.0.0/).
+This is a fixed / No changable section at the top of the file and has the following content:
 
-```markdow
+```markdown
 # 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).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html), and
+ [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+```
+
+### Unreleased changes section:
+
+This section accumulates all the changes that are **not released** yet.
+
+It has to be the first section among sections related a changes section of changes.
+
+The **purpose** is used to communicate how it will be the upcoming release.
 
+The section has the following format:
+```markdown
+## [Unreleased]
+
+<Changes>
+
+```
+
+### Version Section
+
+This section has the changes of a specific version.
+The section has the following format:
+```markdown
 ## [Version] - YYYY-MM-DD
-### Added
-- Details about new features or important additions.
 
-### Changed
-- Changes to existing features, performance improvements, or UI updates.
+<Changes>
+```
 
-### Deprecated
-- Features that are still functional but are marked for removal in future releases.
+There will be zero, one o more than one version sections in the file.
 
-### Removed
-- Features that have been removed from the software.
+> [!IMPORTANT]
+> When there is more than one version section, the order has to be from the newest to the oldest
 
-### Fixed
-- Bug fixes or error corrections.
 
-### Security
-- Security-related changes (such as vulnerability patches or security improvements).
+### Compare Section
 
-## [Unreleased]
-- A list of future changes that have not yet been released.
+This section has a link to compare the current version with the previous one.
+
+For this case the are some special cases
+- The first version has to compare with the previous version.
+- The last version has to compare with the HEAD.
+- The other versions have to compare with the previous version.
+
+In addition, the link depends on the remote repository, so it has to be adapted to the specific one the user choose.
 
+In the following example that shows the format of the section, the link is for a github repository:
+
+```markdown
 ## Compare
-You can compare this version with the previous one or any other version using a version control link:
-- [v1.0.0...v1.1.0](https://repository-url/compare/v1.0.0...v1.1.0)
 
+[unreleased]: https://repository-url/compare/[last-version]...HEAD
+[last-version]: https://repository-url/compare/[last-version]...[previous-version]
+[previous-version]: https://repository-url/compare/[first-version]...[previous-version]
+[first-version]: https://repository-url/releases/tag/[first-version]
+```
+
+### Changes Sections
+
+The changes can be unreleased or versioned as previously it was mentioned.
+keepachangelog classifies changes in the following types:
+- **Added** for new features.
+- **Changed** for changes in existing functionality.
+- **Deprecated** for soon-to-be removed features.
+- **Removed** for now removed features.
+- **Fixed** for any bug fixes.
+- **Security** in case of vulnerabilities.
+
+these types have to follow the following format:
+```markdown
+### [type-of-change]
+- Details about the change.
+- and so on.
+```
+> [!IMPORTANT]
+> When there are not changes of a specific type, the section has not to be created.
+
+
+## Conventional Commits
+
+The convetional commit allows classify the changes in two ways:
+- How the commit wil change the current version of the project.
+- What is the type of change.
+
+So, it is a format created to standardize the commit messages and allow the automation of the versioning of the project.
+
+The format of the commit is the following:
+
+```markdown
+<type>[optional scope]: <description>
+```
+
+For the system the type of the commit is the following:
+- feat: new feature
+- fix: bug fix
+- docs: documentation
+- style: formatting, missing semi colons, etc; no code change
+- refactor: refactoring production code
+- test: adding tests, refactoring test; no production code change
+- chore: updating build tasks, package manager configs, etc; no production code change
+
+The scope will not be used.
+
+Finally, to communicate the breaking changes, the commit has to have a special format:
+```markdown
+<type>!: <description>
+```
+
+## Semantic Versioning
+
+The semantic versioning is a standard to versioning the software. It has the following format:
+```markdown
+<major>.<minor>.<patch>
 ```
 
-## How to resolve the kata
-s
-No matter the language you choose, but you can select some of the approaches below:
-- [Inside-Out TDD](/docs/inside-out-tdd.md)
-- [Outside-In TDD](/docs/outside-in-tdd.md) 
+The version has to be calculated following the following rules:
+- Major version is incremented when you make incompatible API changes.
+- Minor version is incremented when you add functionality in a backwards compatible manner.
+- Patch version is incremented when you make backwards compatible bug fixes.
+
+So, the system has to calculate the next version following the commits since the last release.
+The mapping between the commits and the semantic version change is the following:
+
+| Commit Type | Version Change |
+|-------------|----------------|
+| feat        | Minor          |
+| fix         | Patch          |
+| docs        | None           |
+| style       | None           |
+| refactor    | None           |
+| test        | None           |
+| chore       | None           |
+| <any>!       | Major          |
+
+
+Added for new features.
+Changed for changes in existing functionality.
+Deprecated for soon-to-be removed features.
+Removed for now removed features.
+Fixed for any bug fixes.
+Security in case of vulnerabilities.
 
 
 
-## Acceptance Criteria
-- The changelog file should be in the format of [keepachangelog.com](https://keepachangelog.com/en/1.0.0/).
-- The changelog file should be generated or updated with the release candidate and the current release.
-- The version should be calculated following [Semantic Versioning](https://semver.org/).
-- The changelog file should have a section for each type of commit: Added, Changed, Deprecated, Removed, Fixed, Security.
-- The changelog file should have a section for unreleased changes.
-- The changelog file should have a section to compare the current version with the previous one.
-- The changelog file should have a link to compare the current version with the previous one.
+## Example
+
+The following example shows a changelog file with two versions and unreleased changes.
+
+```markdown
+
+# 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.1.0/),
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html), and
+ [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+## [Unreleased]
+
+### Added
+- New feature 3
+- New feature 4
+
+### Changed
+- Change 1
+
+
+## [1.0.0] - 2021-01-01
+
+### Added
+- New feature 2
+
+
+## [0.1.0] - 2020-12-01
+
+### Added
+- New feature 1
+
+
+## Compare
 
+[unreleased]: https://repository-url/compare/1.0.0...HEAD
+[1.0.0]: https://repository-url/compare/1.0.0...0.1.0
+[0.1.0]: https://repository-url/releases/tag/0.1.0
 
-## References
-- [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
-- [Semantic Versioning](https://semver.org/)
-- [keepachangelog.com](https://keepachangelog.com/en/1.0.0/)
+```
