README, CONTRIBUTING: improve the description of the project
- ID
037db4b- date
2026-07-16 20:13:27+00:00- author
Alex Chan <alex@alexwlchan.net>- parent
c066caf- message
README, CONTRIBUTING: improve the description of the project- changed files
2 files, 55 additions, 62 deletions
Changed files
CONTRIBUTING.md (1234) → CONTRIBUTING.md (878)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6546011..1486c19 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,53 +2,36 @@
You can set up a local development environment by cloning the repo and installing dependencies:
-```shell
-git clone https://github.com/alexwlchan/chives.git
-cd chives
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -e .
+```console
+$ git clone git://alexwlchan.net/projects/chives.git
+$ cd chives
+$ python3 -m venv .venv
+$ source .venv/bin/activate
+$ pip install -e .
```
-If you want to run tests, install the dev dependencies and run the tests:
+If you want to run tests, install the dev dependencies and run the `run_chives_tests.sh` script:
-```shell
-# Activate the virtualenv and install dev dependencies
-source .venv/bin/activate
-pip install -r dev_requirements.txt
+```console
+$ # Activate the virtualenv
+$ source .venv/bin/activate
-# Check formatting
-ruff check .
-ruff format --check .
+$ # Install dev dependencies
+$ pip install -r dev_requirements.txt
-# Check docstrings
-interrogate -vv
-
-# Check types
-mypy src tests
-
-# Run tests
-coverage run -m pytest tests
-coverage report
+$ # Run tests
+$ bash scripts/run_chives_tests.sh
```
To make changes:
1. Create a new branch
-2. Push your changes to GitHub
-3. Open a pull request
-4. Fix any issues flagged by GitHub Actions (including tests, code linting, and type checking)
-6. Merge it!
-
-To create a new version on PyPI:
-
-1. Update the version in `src/chives/__init__.py`
-2. Add release notes in `CHANGELOG.md` and push a new tag to GitHub
-3. Deploy the release using twine:
+2. Work on your changes in that branch, iterating until your change works as expected and the tests pass
+3. Commit your changes
+4. Export your changes to a patch file:
```console
- $ python3 -m build
- $ python3 -m twine upload dist/* --username=__token__
+ $ git format-patch <branch_name> --stdout
```
- You will need [a PyPI API token](https://pypi.org/help/#apitoken) to publish packages.
+5. Email me your patch file for review.
README.md (1588) → README.md (2999)
diff --git a/README.md b/README.md
index 995527e..75b11a1 100644
--- a/README.md
+++ b/README.md
@@ -1,51 +1,61 @@
# chives
-chives is a collection of Python functions for working with my local
-media archives.
+chives is a collection of personal helper utilities for managing, validating, and maintaining local media archives.
-I store a lot of media archives as [static websites][static-sites], and I use Python scripts to manage the sites.
-This includes:
+I store my local media archives as [static websites][static-sites] and use Python scripts to keep everything running smoothly.
+This package bundles the common, reusable code I share across multiple archives and sites.
-* Verifying every file that's described in the metadata is stored correctly
-* Downloading pages from sites I want to bookmark
-* Checking the quality and consistency of my metadata
+[static-sites]: https://alexwlchan.net/2024/static-websites/
-This package has some functions I share across multiple archives/sites.
+## Features
-[static-sites]: https://alexwlchan.net/2024/static-websites/
+Here's what chives includes:
+
+- **Media inspection and processing:** get information like image dimensions and video duration, and convert subtitle files.
+- **Metadata validation:** ensure high-quality metadata by verifying that files in metadata actually exist on disk, and enforcing consistent timestamp formats.
+- **Static site testing:** pytest fixtures to check that static sites can be loaded without console or network errors.
+- **HTTP and date utilities:** standardised helpers for downloading web pages (for bookmarking/archiving) and handling common date patterns.
-## References
+## Design goals
-I've written blog posts about some of the code in this repo:
+My media archives are saved on my personal computer and I want them to last for years (ideally decades), which influences the design of this library:
-* [Cleaning up messy dates in JSON](https://alexwlchan.net/2025/messy-dates-in-json/)
-* [Detecting AV1-encoded videos with Python](https://alexwlchan.net/2025/detecting-av1-videos/)
+1. **Human comprehensibility:** I want to understand every line of code, so everything is written by hand.
+ I understood it once, which gives me a decent chance of understanding it later.
-## Versioning
+2. **Minimal dependencies:** I keep third-party dependencies to a minimum.
+ This is to reduce my exposure to supply-chain attacks and reduce the risk of dependency rot.
-This library is monotically versioned.
-I'll try not to break anything between releases, but I make no guarantees of back-compatibility.
+3. **Rock-solid reliable:** Everything is fully type-checked and throughly tested.
+ I want this to be a reliable foundation for my media archive.
-I'm making this public because it's convenient for me, and you might find useful code here, but be aware this may not be entirely stable.
+## Versioning and stability
-## Usage
+This library is monotonically versioned (releases simply go up sequentially).
-See the docstrings on individual functions for usage descriptions.
+I make breaking changes regularly, and I make no promise of compatibility between versions.
+When I make a breaking change, I update all my local media archives to the latest version immediately and fix the breakage at the same time.
-## Installation
+I've made this repository public because it's convenient for my deployment and to contribute to the public corpus of open-source code for everybody to learn from, but expect things to shift around without warning.
-If you want to use this in your project, I recommend copying the relevant function and test into your codebase (with a link back to this repo).
+## Installation and usage
-Alternatively, you can install the package from PyPI:
+Because this is a personal utility library, I recommend you **copy the code**: duplicate the relevant functions and tests into your codebase (with a link back to this repo for attribution!).
+Having your own copy will protect you from disruption caused by my breaking changes.
+
+If you really want the full package, you can install it from PyPI (but pin the version):
```console
-$ pip install alexwlchan-chives
+$ pip install alexwlchan-chives==42
```
-## Development
+For detailed usage instructions, check the docstrings inside the individual functions.
+
+## Development and feedback
-If you want to make changes to the library, there are instructions in [CONTRIBUTING.md](./CONTRIBUTING.md).
+Want to contribute or tweak something?
+Check out [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup instructions.
## License
-MIT.
+This project is shared under the [MIT license](./LICENSE).