# Generating a changelog

sfp's release command will automate generating a change log that will help the team to understand what are the constituent work items/commits that are part of the release and which artifacts where impacted and what was installed

Here is an example of the changelog that is generated by sfp\\

<figure><img src="https://1646267036-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYLI5Ts7pWhWQV9UaBn3H%2Fuploads%2Fgit-blob-2a4454d55229991ca6c24a37d5eb35574132b993%2Fimage.png?alt=media" alt=""><figcaption><p>A changelog in markdown format rendered in Github</p></figcaption></figure>

The changelog is available as both as a markdown file and also as an associated json file that has the all the necessary information to render the change log accordingly for instance in a different tool

One can instruct the release command to generate the changelog by utilizing the below flags

<pre><code><strong>  -b, --branchname=&#x3C;value>            Repository branch in which the changelog files are located
</strong>  --generatechangelog                 Create a release changelog

</code></pre>

For eg in the below release command, the release command looks for exisiting `releasechangelog.json` to understand the previous release deployed in the environment and it would append the changelog information to both `releasechangelog.json` and `Release-Changelog.md` file

```yaml
sfp release -u prod \
            -p  releasedefn.yaml \
            --npm --scope flxbl \
            -v prod \
             --generatechangelog --branchname changelog
```

Additional attributes to control changelog links for instance are available in the [release definition](https://docs.flxbl.io/flxbl/sfp/releasing-artifacts/release-definitions)

### Identifying work items

Change log displays work item by identify attributes in commit message using a simple regex pattern as provided in the workItemFilters section of your release definition.\
\
For instance, given a commit message with the following message , the work item BE-1836 is identified by the work item filter `` BE-[0-9]{2,5}` ``

```
fix/BE-1836: ⚡ added Config changes for Field type changes (#1629)
* fix: ⚡ added Config changes for Field type changes
```

sfp will identify the part BE-1836 and add a URL link to your work item tracking system by using the provided `workItemUrl` attribute

## Standalone Changelog Generation

You can generate changelogs independently using the `sfp changelog:generate` command:

```bash
sfp changelog:generate \
  --releasename "Release-2.0.0" \
  --artifactdir artifacts \
  --workitemfilter "(JIRA|TASK)-[0-9]{3,4}" \
  --workitemurl "https://yourcompany.atlassian.net/browse" \
  --branchname changelog \
  --directory releases/changelogs
```

## Command Attributes

| Flag                   | Description                                             | Required |
| ---------------------- | ------------------------------------------------------- | -------- |
| `-n, --releasename`    | Name of the release for changelog generation            | Yes      |
| `-d, --artifactdir`    | Directory containing sfp artifacts (default: artifacts) | Yes      |
| `-w, --workitemfilter` | Regex to search for work items in commit messages       | Yes      |
| `-b, --branchname`     | Repository branch where changelog files are stored      | Yes      |
| `--workitemurl`        | Base URL for work items (ID will be appended)           | No       |
| `--directory`          | Directory to write changelog files                      | No       |
| `--limit`              | Limit number of releases to display in markdown         | No       |
| `--showallartifacts`   | Show all artifacts including unchanged ones             | No       |
| `--nopush`             | Create changelog locally without pushing to repository  | No       |
| `--forcepush`          | Force push changes to the repository branch             | No       |

## Multiple Work Item Filters

You can specify multiple regex patterns by separating them with colons:

```bash
--workitemfilter "JIRA-[0-9]+:TASK-[0-9]+:BUG-[0-9]+"
```

This will match any of the patterns in your commit messages.