|
| 1 | +# Getting started |
| 2 | + |
| 3 | +This page describes all steps required for going from zero to viewing a consolidated changelog. |
| 4 | + |
| 5 | +## 1. Prerequisites |
| 6 | + |
| 7 | +Ensure you have `git` installed and available. |
| 8 | + |
| 9 | +## 2. Install |
| 10 | + |
| 11 | +Follow one of the installation ways described in [`./install.md`](./install.md). |
| 12 | + |
| 13 | +## 3. Create a changelog fragment |
| 14 | + |
| 15 | +From the root folder of the repository run: |
| 16 | + |
| 17 | +``` |
| 18 | +$ elastic-agent-changelog-tool new "my test fragment" |
| 19 | +``` |
| 20 | + |
| 21 | +This will create `./changelog/fragments/<timestamp>-my-test-fragment.yaml` with this content: |
| 22 | + |
| 23 | +```yaml |
| 24 | +# one of: |
| 25 | +# - breaking-change: a change to previously-documented behavior |
| 26 | +# - deprecation: functionality that is being removed in a later release |
| 27 | +# - bug-fix: fixes a problem in a previous version |
| 28 | +# - enhancement: extends functionality but does not break or fix existing behavior |
| 29 | +# - feature: new functionality |
| 30 | +# - known-issue: problems that we are aware of in a given version |
| 31 | +# - security: impacts on the security of a product or a user’s deployment. |
| 32 | +# - upgrade: important information for someone upgrading from a prior version |
| 33 | +# - other: does not fit into any of the other categories |
| 34 | +kind: feature |
| 35 | +# Change summary; a 80ish characters long description of the change. |
| 36 | +summary: |
| 37 | +# Long description; in case the summary is not enough to describe the change this field accomodate a description without length limits. |
| 38 | +# description: |
| 39 | +# Affected component; a word indicating the component this changeset affects. |
| 40 | +component: |
| 41 | +# PR number; optional; the PR number that added the changeset. |
| 42 | +# If not present is automatically filled by the tooling finding the PR where this changelog fragment has been added. |
| 43 | +# NOTE: the tooling supports backports, so it's able to fill the original PR number instead of the backport PR number. |
| 44 | +# Please provide it if you are adding a fragment for a different PR. |
| 45 | +# pr: 1234 |
| 46 | +# Issue number; optional; the GitHub issue related to this changeset (either closes or is part of). |
| 47 | +# If not present is automatically filled by the tooling with the issue linked to the PR number. |
| 48 | +# issue: 1234 |
| 49 | +# Repository URL; optional; the repository URL related to this changeset and pr and issue numbers. |
| 50 | +# If not present is automatically filled by the tooling based on the repository this file has been committed in. |
| 51 | +# repository: https://github.com/elastic/elastic-agent-changelog-tool |
| 52 | +``` |
| 53 | + |
| 54 | +Ensure `kind` is correct and fill the `summary` field with a brief description. You can ignore `component`, but you must set `pr`, `issue` and `repository` manually, the logic to fill them automatically is still work in progress. |
| 55 | + |
| 56 | +Save and close the file. |
| 57 | + |
| 58 | +## 4. Create the consolidated changelog |
| 59 | + |
| 60 | +From the root folder of the repository run: |
| 61 | + |
| 62 | +``` |
| 63 | +$ elastic-agent-changelog-tool build --version 0.1.0 |
| 64 | +``` |
| 65 | + |
| 66 | +This will create `./changelog.yaml` with content similar to this: |
| 67 | + |
| 68 | +```yaml |
| 69 | +version: 0.1.0 |
| 70 | +entries: |
| 71 | + - summary: Add Changelog Fragment creation |
| 72 | + description: "" |
| 73 | + kind: feature |
| 74 | + pr: 13 |
| 75 | + issue: 21 |
| 76 | + timestamp: 1649924282 |
| 77 | + file: |
| 78 | + name: 1649924282-changelog-fragment-creation.yaml |
| 79 | + checksum: 10bf1bf67509a524e48f0795be75c278e29c0b47 |
| 80 | + |
| 81 | +``` |
| 82 | + |
| 83 | +There will be multiple entries, one for each files in `changelog/fragments`. |
| 84 | + |
| 85 | +**NOTE:** the version is currently hard coded to `0.1.0` (the first version for `elastic-agent-changelog-tool`). |
0 commit comments