diff --git a/README.md b/README.md index 7536ec7..fd4e309 100644 --- a/README.md +++ b/README.md @@ -126,3 +126,65 @@ reads this key from the environment variable `FIMFICTION_ACCESS_TOKEN`. Any data downloaded from Fimfiction is stored in the current working directory, typically in the `worktree` subdirectory. The same thing goes for rendered stories, built archives, or anything else related to the release process. + + +# Process + +The process for building a new Fimfarchive release consists of a few simple +steps. Before starting, make sure you have the previous version of Fimfarchive +nearby, as well as a Fimfiction APIv2 key. Also, remove any previous `worktree` +directory from the current working directory. Some of the commands mentioned +below are currently only available in feature branches. + +- **Update**: Invoke the `update` subcommand to refresh all stories. This takes + about one month since _all_ story metadata has to be traversed. Story data + isn't downloaded unless changes have been made since the last release. Use + the `--refetch` flag if all data should be updated regardless of if there + have been any changes. Write down the `Started` and `Done` dates for later. + +- **Render**: Use the `render` subcommand to generate EPUB-files for all + stories with updated content. The subcommand requires `ebook-convert` from + Calibre to be installed and accessible from the command line. Fimfarchive + will usually keep the CPU maxed out for a few hours during this step. + +- **Count**: The `count` subcommand compares the upcoming release with the + previous one. The output mainly consists of statistics for the changelog. + +- **Document**: Update the documentation in `docs/readme.tex` for the upcoming + release. Change the document title, add a row to the changelog table, and a + new changelog subsection. Render the document _a few times_ with `lualatex` + and place the results in `worktree/extras` as `readme.pdf`. + +- **About**: Create an `about.json` file in `worktree/extras`. The file has + three keys named `version`, `start`, and `end`. Each key has a simple date + string like `20201201` as its value. Preferably use the file included with + the previous release as a template to keep things consistent. + +- **Build**: Create a `build` directory in `worktree`, and then run the `build` + subcommand. Expect this to take up to 15 minutes depending on the machine. + The resulting archive will be written to the `build` directory. + +- **Verify**: Go through the archive to check that everything looks good. One + tip is to test the CRC checksums of both the outer ZIP-archive and internal + EPUB-files. Sample some old and new stories to check that they look right. + Successfully opening the archive with [Fimfareader] can help prove that the + metadata has all of the required fields with the correct data types. + +- **Patch**: Create an [xdelta3] patch if applicable. It's important to allow + `xdelta3` to use a lot of memory since it otherwise has trouble seeing the + similarities between the archives. For example, `xdelta3 -B 2147483648 -e -s + ` uses the maximum allowed value of 2 GiB. + +- **Torrent**: Create a torrent file if applicable. Using a private tracker + with a whitelist is preferable since public ones could be flaky or have poor + response times. However, it's usually a good idea to include a few public + trackers as well to improve availability. Set the chunk size so that the + torrent is split into somewhere between 1000 and 2000 pieces. Values outside + that range could cause performance issues or prevent the torrent from being + easily distributed via magnet links. + +- **Release**: Upload, announce, and distribute the release! + +[Calibre]: https://calibre-ebook.com +[Fimfareader]: https://github.com/JockeTF/fimfareader +[xdelta3]: http://xdelta.org