-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Lots of documentation updates. Some tweaks:
- compose.yaml: - Comment out secrets, add tag for Easticsearch image. - pyproject.toml: - Better VCS usage.
- Loading branch information
Showing
9 changed files
with
918 additions
and
28 deletions.
There are no files selected for viewing
Validating CODEOWNERS rules …
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
# Global Ownership | ||
* @sidneys1 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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> |
Oops, something went wrong.