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 the docs with the new version #17

Merged
merged 2 commits into from
Aug 7, 2023
Merged

update the docs with the new version #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
74699c9
update the docs with the new version
falcucci Aug 7, 2023
00e5da7
adding contributors to template
falcucci Aug 7, 2023
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
171 changes: 6 additions & 165 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,119 +3,36 @@ Changelog-it

Changelog-it is a command line tool that helps you manage a changelog file for your project. It makes it easy to add new entries to the changelog, and it also provides commands to help you format and present the changelog in a way that is easy for users to read.

The tool is written in JavaScript and can be installed using npm. Once it's installed, you can run changelog-it from the command line to see a list of available commands.
The tool is written in Rust and can be installed using `cargo`. Once it's installed, you can run changelog-it from the command line to see a list of available commands.

Some of the features of the tool include:

- Adding entries to the changelog: The add command allows you to add a new entry to the changelog. You can specify the type of entry (e.g. `Added`, `Changed`, `Fixed`), a summary of the change, and an optional description.
- Formatting the changelog: The format command can be used to format the changelog in a way that is easy to read. It groups entries by type and sorts them by date.
- Generating a release file: You can use the release command to generate a markdown file with the latest changes and upload it to your repository.
- Customizable templates: You can set custom templates in order to format the generated changelog to your specific needs.
- The tool is flexible and easy to use, and it's a great way to keep track of the changes in your project.

You can start using the tool by installing it with npm, and following the documentation provided in the page for further usage.

here are some available integrations we do to generate the release:

| Jira | Github | Gitlab | Slack |
|--------------| --------------| --------------| --------------|

For example:

```bash
changelog-it --range origin/prod...origin/master --release --gmudd --summary "some summary..."
```

take a look on [this](https://github.com/falcucci/changelog-it/blob/master/changelog.example.md) file to check how it will looks like

You can also have it automatically post to slack by using the `--slack` flag.

## How it works
| Github
| --------------

The script looks for Jira issue keys, surrounded by square brackets (i.e. `[DEV-123]`), in the git commit logs. When it finds one, it associates that Jira issue ticket with that commit and adds it to the changelog.
take a look on [this](https://github.com/falcucci/changelog-it/blob/master/templates/example.md) file to check how it will looks like

## Installation

```bash
npm install -g -S @falcucci/changelog-it
```

## Configuration

You'll need to configure Jira before you can use this effectively. Create a file called `changelog.config.js` and put it at the root of your workspace directory; where you'll call the `jira-changelog` command from.

Here's a simple example with sample Jira API values:

```javascript
module.exports = {
jira: {
api: {
host: "yoursite.atlassian.net",
username: "jirauser",
password: "s00persecurePa55w0rdBr0"
},
}
}
cargo install changelog-it
```

To see all values suported, look at the `changelog.config.js` file at the root of this repo.

## Usage

```bash
changelog-it --range origin/prod...origin/master --slack --release
```

Assuming you deploy from the prod branch, this will generate a changelog with all commits after the last production deploy to the current master version.

If you define `sourceControl.defaultRange` in your config, you can run the command with the `--range` flag:

```bash
changelog-it
```

## Releases

You can automatically attach Jira issues to a release with the `--release` flag. For example, let's say we want to add all issues in the changelog to the "sprint-12" release:

```bash
changelog-it --range origin/prod...origin/master --release sprint-12
```

This will set the `fixVersions` of all issues to "sprint-12" in Jira.

## Slack

You can also have the script automatically post to slack.

First, get an API token from Slack for your workspace:
https://api.slack.com/tokens

Then add slack to your configuration file:

```javascript
module.exports = {
slack: {
apiKey: 'asdlfkjasdoifuoiucvlkxjcvoixucvi',
channel: '#changelogs'
},
jira: {
api: {
host: "myapp.atlassian.net",
username: "jirauser",
password: "s00persecurePa55w0rdBr0"
},
}
}
```

* Add your API token to `slack.apiKey`.
* `slack.channel` is the channel you want the script to send the changelog to.

Then simply add the `--slack` flag to the command:

```bash
changelog-it --range origin/prod...origin/master --slack
changelog-it --owner rust-lang --project rust --release 1.73.0 --github-token <token>
```

You can automate it generating semantic version tags using the following command:
Expand All @@ -126,79 +43,3 @@ or creating an alias in your `.aliases` file:
```bash
alias release-me='curl -LsS https://raw.githubusercontent.com/falcucci/release-me/master/changelog-it.sh | bash -s $1 $2'
```
and run:
```bash
release-me <semantic-version> <summary>
```

### GitLab CI

**note: this requires npm to run+**

Store the following envs in [GitLab CI variable](https://docs.gitlab.com/ee/ci/variables/#variables).

| name | description |
| ---- | ----------- |
| `GITLAB_API_KEY` | Gitlab api key |
| `SLACK_API_KEY` | Slack api key |
| `SLACK_CHANNELS` | Slack channels ids separeted by comma |
| `GMUD_CHANNEL` | Slack gmud channels ids separeted by comma |

#### .gitlab-ci.yml sample

```yaml
changelog:
script:
- changelog-it v1.0.0...v2.0.0 --release --gmud
# Or using aliases above if you have it in a package.json
- npm run changelog
# Or using some script
- curl -LsS https://raw.githubusercontent.com/falcucci/release-me/master/ci-changelog-it.sh | bash -s
```

You can use changelog-it to generate changelogs and gmuds from anywhere with following
environment variables.

```shell
$ export GITLAB_API_KEY=haya14busa
$ export SLACK_API_KEY=haya14busa
$ export SLACK_CHANNELS=APOISFDUP
$ export GMUD_CHANNEL=PAOISUFOPUAS
```

## API
The code used to generate the changelogs can also be used as modules in your JavaScript.
See the module source for documentation.

For example:

```bash
npm install -S @falcucci/changelog-it
```

```javascript
const Config = require('@falcucci/changelog-it').Config;
const SourceControl = require('jira-changelog').SourceControl;
const Jira = require('jira-changelog').Jira;

const gitRepoPath = '/home/user/source/'

// Get configuration
const config = Config.getConfigForPath(gitRepoPath);

// Get commits for a range
const source = new SourceControl(config);
const range = {
from: "origin/prod",
to: "origin/master"
};
source.getCommitLogs(gitRepoPath, range).then((commitLogs) => {

// Associate git commits with jira tickets and output changelog object
const jira = new Jira(config);
jira.generate(commitLogs).then((changelog) => {
console.log(changelog);
});

});
```
25 changes: 25 additions & 0 deletions templates/example.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# rust-lang/rust - 1.73.0 (2023-08-07)

- [Issue numbers are enforced on active features; remove FIXME](https://github.com/rust-lang/rust/pull/114556)
- [Remove FIXME about NLL diagnostic that is already improved](https://github.com/rust-lang/rust/pull/114558)
- [update Miri](https://github.com/rust-lang/rust/pull/114560)
- [stabilize abi_thiscall](https://github.com/rust-lang/rust/pull/114562)
- [Rollup of 6 pull requests](https://github.com/rust-lang/rust/pull/114565)
- [Rollup of 8 pull requests](https://github.com/rust-lang/rust/pull/114569)
- [[miri][typo] Fix a typo in a vector_block comment.](https://github.com/rust-lang/rust/pull/114570)
- [CI: do not hide error logs in a group](https://github.com/rust-lang/rust/pull/114573)
- [:arrow_up: `rust-analyzer`](https://github.com/rust-lang/rust/pull/114576)
- [Rollup of 9 pull requests](https://github.com/rust-lang/rust/pull/114585)

### Contributors

- [Enselic](https://github.com/Enselic)
- [Enselic](https://github.com/Enselic)
- [RalfJung](https://github.com/RalfJung)
- [Trolldemorted](https://github.com/Trolldemorted)
- [matthiaskrgr](https://github.com/matthiaskrgr)
- [matthiaskrgr](https://github.com/matthiaskrgr)
- [ttsugriy](https://github.com/ttsugriy)
- [Kobzol](https://github.com/Kobzol)
- [lnicola](https://github.com/lnicola)
- [matthiaskrgr](https://github.com/matthiaskrgr)