CreateChangeFile step

A "change file" is a specially formatted Markdown file that is used both to determine the next version of your project and to generate a changelog. This step will interactively create a new change file in the .changeset directory of your project (creating that directory if missing). When a PrepareRelease step runs, it will combine both change files and any conventional commits since the last release to generate changelogs and update versions for any configured packages.

Example

With a knope.toml file that looks like this:

[packages.first]
versioned_files = ["first/Cargo.toml"]
changelog = "first/CHANGELOG.md"
extra_changelog_sections = [
    { name = "Poems 🎭", types = ["poem"] }
]

[packages.second]
versioned_files = ["second/Cargo.toml"]
changelog = "second/CHANGELOG.md"

[[workflows]]
name = "document-change"

[[workflows.steps]]
type = "CreateChangeFile"

You could run knope document-change to start a new change file. First, you will be prompted to select the packages that this change affects, for this example, we check off both packages.

- [x] first
- [x] second

For each package, you will be prompted to select the type of change you are documenting. The available change types are "Breaking", "Feature", "Fix", and any of the custom types configured in extra_changelog_sections.types. For the first package, this will look like:

Enter the type for the `first` package:

Breaking
Feature
Fix
> poem

For the second package, we would not have the poem option. Next, you will be prompted write a short summary of the change (a few words). The summary will be used both as the name of the file and a header in the changelog generated by PrepareRelease.

Let's say we enter the summary `[i carry your heart with me(i carry it in]`, this step will then generate a file .changeset/i_carry_your_heart_with_mei_carry_it_in.md with the following contents:

---
first: poem
second: major
---

#### `[i carry your heart with me(i carry it in]`

If that brief summary is not enough, you should then edit this file and add more detail below the generated heading, using all the Markdown features you want!

---
first: poem
second: major
---

#### `[i carry your heart with me(i carry it in]`

**E. E. Cummings**

<pre>
i carry your heart with me(i carry it in
my heart)i am never without it(anywhere
i go you go,my dear;and whatever is done
by only me is your doing,my darling)
                                   i fear
no fate(for you are my fate,my sweet)i want
no world(for beautiful you are my world,my true)
and it’s you are whatever a moon has always meant
and whatever a sun will always sing is you

here is the deepest secret nobody knows
(here is the root of the root and the bud of the bud
and the sky of the sky of a tree called life;which grows
higher than soul can hope or mind can hide)
and this is the wonder that's keeping the stars apart

i carry your heart(i carry it in my heart)
</pre>

When you are done, you can run knope document-change again to create another change file. When you are ready to release, run PrepareRelease to combine all the change files and conventional commits into a changelog and update the versions of any configured packages. The type of the change for each package will determine where it is placed in the changelog: so first/CHANGELOG.md will have a ### Poems 🎭 section and second/CHANGELOG.md will have a ### Breaking Changes section, each containing the summary and body of the change.

For completeness, this is what the changelog for first would look like (if there had been no other changes):

### Poems 🎭

#### `[i carry your heart with me(i carry it in]`

**E. E. Cummings**

<pre>
i carry your heart with me(i carry it in
my heart)i am never without it(anywhere
i go you go,my dear;and whatever is done
by only me is your doing,my darling)
                                   i fear
no fate(for you are my fate,my sweet)i want
no world(for beautiful you are my world,my true)
and it’s you are whatever a moon has always meant
and whatever a sun will always sing is you

here is the deepest secret nobody knows
(here is the root of the root and the bud of the bud
and the sky of the sky of a tree called life;which grows
higher than soul can hope or mind can hide)
and this is the wonder that's keeping the stars apart

i carry your heart(i carry it in my heart)
</pre>