README.md

Dungeon Time
============

Time for dungeons!

https://lab.burn.capital/chaz/dungeon-time

Dungeon Time is a BDSM dungeon space management and scene timing app made by
and for the community, not for profit.  Dungeon Time respects your safety and
privacy: no personal data is collected, just your chosen scene name.  Nothing
is shared outside the event staff.

Dungeon Time is an alpha-quality, evolving hobby project under active
development.  Releases are available as Android APKs; see below for
installation instructions.  Dungeon Time also runs on Linux if you build it
from source.  It's tested on both platforms (though, um, currently lacks
automated tests).  Dungeon Time is written in Dart/Flutter, and in theory could
run on any platform [Flutter supports](https://docs.flutter.dev/reference/supported-platforms)
with a little work.

### Contributions

Contributions of all kinds are welcome from all!  Please email the author
(address below)—he especially appreciates bug reports and patches, but will
happily field questions and consider suggestions as well.  Thank you.

**Credits**

Dungeon Time is only possible thanks to these outstanding contributors:

 * Keegan, our patient tester and tireless dungeon host
 * The wonderful, hard-working event staff making space for our little
   community every week
 * All the beautiful people everywhere who support local communities by showing
   up to fun events and tipping the staff, dancers, and hosts

Thank you!

### Copyright & License

Dungeon Time is written and maintained by Charles Lindsay.  He prefers to be
reached via email, at <chaz@burn.capital>.

Dungeon Time project and source code copyright © 2024, 2025 Charles Lindsay.
Dungeon Time is free software, released under the terms of the GNU AGPL,
version 3; see [`LICENSE.md`](LICENSE.md).

Dungeon Time is distributed in the hope that it will be useful, but without any
warranty; without even the implied warranty of merchantability or fitness for a
particular purpose.  See the AGPL for details.

### Icons

Dungeon Time uses the standard set of Material icons provided by Flutter, plus
some custom icons (see [`svg/*`](svg)) designed by the Dungeon Time authors.

Install (Android)
-----------------

1. First, make sure your device's web browser app has permission to install
   APKs: (here's [a more detailed guide with screenshots and FAQs])
   * Launch your device's *Settings* app.
   * Go to *Apps*.
   * Go to *Special access* or *Special app access*, maybe under a `⋮`
     ("kebab") menu.
   * Go to *Install unknown apps*.
   * Find and enable your web browser app's permission from the list, e.g.
     Firefox or Chrome.
2. Find and download the latest release of Dungeon Time for your device from
   the [Releases] page in your web browser.
   * The latest release is listed first on the Releases page.
   * Each release has APK downloads for each of the three ABIs supported by
     Flutter's tooling.  You'll almost certainly want the `arm64-v8a` version.
     A few devices use `armeabi-v7a` and fewer still `x86_64`, so if you're
     unsure which APK to download, try them in that order.
   * Accept/continue if prompted about the file being potentially harmful.
3. Tap on the downloaded APK and install it.
   * I don't know how to find the downloaded APK on your device, sorry.  I
     don't even know where to find it on mine most of the time.  Maybe there is
     a list of *Downloads* in a menu somewhere in your browser.
   * Tapping on the APK should bring up a little confirmation menu with the
     option to *Install*.
4. Now you can find and run Dungeon Time from your device's app launcher.
   * And I hope you enjoy it!
5. If you want to shore up your device security, go back and revoke your
   browser's permission to install apps.
   * The process is the same as step 1 above, except for disabling the app's
     permission at the end.

[a more detailed guide with screenshots and FAQs]: https://web.archive.org/web/20241204090030/https://www.lifewire.com/install-apk-on-android-4177185
[Releases]: https://lab.burn.capital/chaz/dungeon-time/-/releases

Maintainer Notes
----------------

### Creating New Icons

New icons should roughly follow the [material icon guidelines].  There's an
Inkscape template in [svg/material-icon-template.svg] you might find handy.

SVGs should be [simplified], then manually cleaned up in a text editor before
being added to the project--basically, you want just one big path declaration.
Use [FlutterIcon] to convert the SVGs into a TTF usable as a Flutter `Icon`.

[material icon guidelines]: https://m3.material.io/styles/icons/designing-icons
[svg/material-icon-template.svg]: svg/material-icon-template.svg
[simplified]: https://github.com/fontello/fontello/wiki/How-to-use-custom-images#preparing-images-in-inkscape
[FlutterIcon]: https://www.fluttericon.com/

### Pre-(and-Post-)Release Checklist

 - [ ] Make sure `ChangeLog.md` is up to date
 - [ ] Update `oss_licenses.dart`: `flutter pub run flutter_oss_licenses:generate.dart`
 - [ ] Bump version in `pubspec.yaml` **and `lib/assets.dart`**, update
   `ChangeLog.md` with new release version
 - [ ] Double check about/license pages for correctness (version, copyright
   year, contributors, etc.)
 - [ ] Commit everything; create and push tag:
   * `git tag -s -m 'Dungeon Time v...' v...`
   * `git push --tags`
 - [ ] Wait for CI build; set CI job to keep artifacts forever
 - [ ] Create release on gitlab; add download/browse links to artifacts
 - [ ] Better give it a smoke test!
 - [ ] Add `+git` to version in `pubspec.yaml` **and `lib/assets.dart`**,
   update `ChangeLog.md` with new `Unreleased` section
 - [ ] Upgrade flutter version and pub packages:
   * `flutter upgrade`
   * `flutter pub upgrade`, or `flutter pub upgrade --major-versions` if
     possible
   * Check `flutter pub outdated`
   * Bump flutter version in `.gitlab-ci.yml` if necessary
   * Better update `oss_licenses.dart` again (see above)
   * Smoke test both linux and android builds again