Skip to content

Commit

Permalink
Lots of documentation updates. Some tweaks:
Browse files Browse the repository at this point in the history
- compose.yaml:
  - Comment out secrets, add tag for Easticsearch image.
- pyproject.toml:
  - Better VCS usage.
  • Loading branch information
Sidneys1 committed Jun 5, 2024
1 parent 9de7d80 commit f7e0a41
Show file tree
Hide file tree
Showing 9 changed files with 918 additions and 28 deletions.
2 changes: 2 additions & 0 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Global Ownership
* @sidneys1
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,9 @@ src/memoria/web/www/templates/*.css
src/memoria/web/www/templates/*.css.map
src/memoria/web/www/static/*.css
src/memoria/web/www/static/*.css.map

# Misc
TODO.md
get-ff-sync.sh
/data/
/secrets/
47 changes: 47 additions & 0 deletions BUILDING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
Building
========

For instructions on performing a release, see the [Contribution Guide](./CONTRIBUTING.md#performing-a-release).

Python
------

Memoria is built using the Python build system [Hatch][hatch]. To build a wheel or source tarball, you must:

1. Ensure Sass runs against any files in the [templates][templates-folder] and [static][static-folder] web content
folders.

```sh
# For example, using NPX:
npx sass src/memoria/web/www/static/:src/memoria/web/www/static/ \
src/memoria/web/www/templates/:src/memoria/web/www/templates/
```

2. Build the package with `hatch build`:

```sh
hatch build
```

The resulting source archive and wheel will be output in `./dist`.

[hatch]: https://github.com/pypa/hatch
[templates-folder]: ./src/memoria/web/www/templates/
[static-folder]: ./src/memoria/web/www/static/

Containers
----------

The [Containerfile](./Containerfile) builds Memoria entirely, including running Sass:

```sh
podman build -t ghcr.io/sidneys1/memoria .
# Or
podman-compose build memoria
# If using the Docker toolchain you may need to provide the -f parameter:
docker build -f Containerfile -t ghcr.io/sidneys1/memoria .
# Or
docker-compose -f compose.yaml build memoria
```
41 changes: 41 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
Changelog
=========

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

{{{Unreleased}}}
----------------

Initial project commit, basic functionality intact.

<!-- TODO: Any additional notes for this release. -->

### Added

- All base functionality.
- GitHub Actions to build and publish Python packages and container images.

<!--------------------------------------------------------------------------------------------------------------------->

<template>
{version}
---------

General description of this release.

Any additional notes for this release.

### Added

<!-- List of things that have been added. Be sure to @mention contributors, #tag relevant discussions/issues/PRs. -->
- A changelog (@sidneys1).

### Changed
### Deprecated
### Removed
### Fixed
### Security
</template>
117 changes: 117 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
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>
Loading

0 comments on commit f7e0a41

Please sign in to comment.