Contributing
============

General guidelines:
- So far the code has been using [isort] and [yapf] for formatting.
- Comments shouldn't be useless (e.g., describing obvious code).
- Documentation and commit messages[^1] should all be in Markdown.

[isort]: https://github.com/PyCQA/isort
[yapf]: https://github.com/google/yapf
[^1]: The first line should be generally unformatted. Backticks and GitHub references are allowed.

Performing a Release
--------------------

1. Commit the following changes in a pull request to bring the release branch (e.g., `v0.1`) into `main`:
   - Ensure the version in [`__about__.py`][version-file] has been updated. This can be done manually or with Hatch.

     <details><summary>Updating the version with Hatch</summary>

     `hatch version <desired-version>` can be used to set the version automatically. `hatch version <segment>` can be used
     to increment the specified [segment][hatch-segments]. Some examples:

     ```sh
     hatch version  # Get current version
     # 0.1b

     hatch version 0.1 # Set version to 0.1
     # Old: 0.1b
     # New: 0.1
   
     hatch version minor # Increment the minor version.
     # Old: 0.1b
     # New: 0.2
   
     hatch version major # Increment the major version. `hatch version release` would do the same.
     # Old: 0.1b
     # New: 1.0
     ```

     </details>

   - Update the [Changelog](./CHANGELOG.md) with release notes. You may need to view the commit history since the last
     release to identify any changes that were missed.

2. A maintainer will merge the above PR using a signed merge commit:

   ```sh
   # Using "v0.1a" as an example version
   git checkout main
   git merge --no-ff --sign --edit ${target as specified in PR}
   ```

   An editor will open, enter the changelog section for this release, with [some formatting tweaks][tweaks].
   
   Don't forget to `git push` the merge commit.

3. A maintainer will create a signed and annotated tag with the current release's release notes:

   ```sh
   # Using "v0.1a" as an example version
   git tag --gpg-sign v0.1a
   ```

   An editor will open, enter the changelog section for this release, with [some formatting tweaks][tweaks] (same as the
   merge commit).

   Don't forget to `git push origin refs/tags/v0.1a` (for example).

4. A maintainer will create [a new GitHub release][gh-release] for the tag that was just created. The title will be the
   [Semantic Versioning](https://semver.org/spec/v2.0.0.html) version of the release. The release notes will be the same
   [tweaked][tweaks] content of the changelog as the merge commit and tag.

   If the release is a pre-release (`a`, `b`, or `rc` suffixes) make sure to check the "Set as a pre-release" box.


> [!NOTE]
> The release packages for Memoria are all generated by GitHub Actions. No manual action is required.

[hatch-segments]: https://hatch.pypa.io/dev/version/#supported-segments
[version-file]: ./src/memoria/__about__.py
[tweaks]: #tweaking-the-changelog-for-git-messages
[gh-release]: https://github.com/Sidneys1/Memoria/releases/new

---

Tweaking the Changelog for Git Messages
---------------------------------------

You'll want to exclude the level 2 heading, and convert the level 3 headings to nested lists. You can otherwise keep
Markdown formatting intact.

<details><summary>Example</summary>

As an example example, for this changelog section:

```md
v0.1a
-----

A release!

### Added

- Added a *brand new* [changelog](./CHANGELOG.md).
```

You would enter the following:

```md
A release!

Added:
- Added a *brand new* [changelog](./CHANGELOG.md).
```

</details>
