# Tobira 1.0 Release Discussion

Planned release: **before 2022-07-09** (before the OC meetup/conf). That's
1 week Julian + 2 weeks Lukas (3 minus 1 week slack for talk preparation).

## Open questions
- We use GitHub releases and upload the compiled binary, right?
- Yes
- Linux packages?
- No, not for now
- Tobira Module in community when?
- Soon. In 12.
- Community acceptance? "Consider them überzeugt"
- Migration automatically when starting Tobira? Or requiring explicit `tobira db migrate`? How does this work with `tobira check`?
- Keep it automatic. People should have DB backups and we can't really think of a case where migrations are done unwanted.
- Remove configurable auth-headers?
- Yes, remove
- Do we only announce it at the conf? Or before already? And in any case: over what channels?
- Time it with conf, mabye even release DURING talk
- Also mailing list + blog post

| | Tobira-Modul API | MeiliSearch | PostgreSQL |
| ----------------- | ---------------- | ----------- | ---------- |
| Required version: | `^1.0` | `^0.27.2` | `^10` |

<br>
<br>

---

## What do we still want to include in 1.0?

- [x] Realm names from blocks (because: DB schema changes) -> Lukas
- [x] Versioning docs
- [x] "Make search honor our decision regarding unlisted elements"
- [x] Host realms in search index and UI
- [x] Some way of versioning of the harvest API
- [x] [Investigate using `reshape` for zero-downtime DB migrations](https://github.com/elan-ev/tobira/issues/350)
- [x] Remove the `theme.fonts` config value (will likely change in the future)
- [x] Move all "queue for reindex" to DB triggers -> in review
- [x] Just Paella? -> *in review*
- [x] Get rid of `floof` (and overhaul build system)
- [x] Automatically build release artifacts in GitHub actions
- [x] "Waiting events" (because: DB schema changes)
- [x] Rename foreign key columns to not `_id`?
- [x] Don't trigger CI on tag push
- [x] Expose startTime/endTime in API & improve display of live events? ("anstehend")
- [x] Dickes Testen
- Deploy bei bern?!
- [x] Readme update
- [x] Write Changelog

### Maybe

- [ ] mountSeries verbesserungen
- sollte den Namen der Seite setzen als abhängigkeit von serie
- sollte schon serien title speichern
- [ ] Think about the frontend noticing when the backend was updated (would result in incompatible API versions)
- [ ] Maybe setup a nice "rendered docs" page, preferably with an option to switch between versions
- [ ] Do we need more docs on something specific?
- Tobira Links (in particular, direct links)

<br>
<br>

---

## Part of the release

- Right before release checking:
- Anything bad in the existing DB migrations?
- Any config values that we likely want to change/throw out soon?
- Any glaring problems with the auth system?
- Come up with some way to automatically build binaries?
- Check in CI that the existing DB migrations are never changed.
- We could solve two problems at once: have a DB backup/snapshot of Tobira 1.0. That snapshot is used as starting point for all other CI tasks. Means: changing the existing migrations will fail and: we can speed up the initial sync.

<br>
<br>

---

## Versioning

### What kind of versioning scheme?

| Semantic (e.g. `major.minor.patch`) or opaque (e.g. dates)? |
| --- |

I, Lukas, certainly prefer a semantic versioning scheme. I suspect opposition :P Therefore, some points:

- "Semantic versioning means nothing, especially so for an app with UI. What even is a breaking change?"

> Fair point. "Semantic versioning" alone means nothing as the definition of "breaking" and "backwards compatible" depends strongly on the context. Developers relying too much on SemVer as if it's an exact specification are mistaken/will encounter problems.
>
> **But** we can define what these terms mean for Tobira. We can simply list the changes we allow in which version bump. Also, Tobira has a lot more "non-UI parts" than Studio, Editor or AT, for example. See below for a list of things that I think it makes sense to define a stability guarantee for.

- "It's more work because we need to define what we consider a breaking change! And for every release, we need to check which digit we need to increment!"

> The first point is merely one time work of a couple hours. And we need to talk about most of that anyway.
> And the extra work for each version is minimal (automatically happens while writing/checking the changelog). Also very likely, and ideally, we already know before the release what kind of release will come next.

- Using a SemVer-like versioning scheme shows anyone at a glance what kind of changes they can expect in a new version -- *roughly*. And even if it's just "roughly", there is value in it. Using an opaque identifier gives up on that completely.

- Admins can read the short versioning document (see below) to know exactly what kind of changes they can expect. They can adjust their update workflow based on that. They don't have to waste time worrying about changes we won't make, and they also know what they have to look out for.

- It lays out a rough idea of how often certain types of changes are done. It also makes us developers be cautious of high impact breaking changes by doing them less often. By giving us this framework, it incentives us to do some changes less often.

→ I think there are *some* benefits to some kind of semantic versioning for almost no cost/work at all. Yes, SemVer is often misunderstood and relied on too heavily, but just using opaque identifiers seems like an overreaction and throwing out the baby with the bathwater. Something something perfect is the enemy of good.

### What changes are allowed?

The following is just a list of things I could think of that we should think about. I have a suggestion for most of these. The full written-out suggestion of the versioning guarantee can be found in [this document](https://hackmd.io/FdKV2ubpSsqRrfrmlpM3kQ).

- DB
- Schema changes?
- Requiring newer versions of PostgreSQL? At least drop EOL versions?
- Search Index:
- Meili Updates/requiring a new version
- Index rebuild required
- Config file backwards compatibility?
- Login system backwards compatibility
- GraphQL API
- The CLI
- Emitted HTML to be styled via CSS?
- Functionality
- Remove features?
- Vastly change UI of certain pages?
- Translations?
- On the Opencast side
- New Tobira module?
- New Opencast version?
- Other new Opencast requirement (e.g. disable static file auth)

### Tobira <-> OC Communication

- Do we require the exact same versions?
- Do we have some semantic versioning as well so that Tobira can figure out whether the given API is compatible?
- Do we just not do any checking at all and rely on some other errors (deserialization, ...) to occur?
- How likely is it that incompatible APIs silently corrupt stuff?
- But then `tobira check` cannot know compatibility ahead of time
- Should we have Tobira Module releases so that we can refer to specific "versions" other than using commit hashes? Tobira needs to somehow express what harvest API it requires.

::: success
- Tobira soll mit mehreren Harvest-Versionen funktionieren
- Soll einfach feststellen können, ob kompatibel
- Vermutlich sowas wie `x.y`
:::

## Fragen

- Eine oder mehrere Versionen
- Eine
- Opencast-Kompatibilität
- Pragmatisch sein
- Wann Migrationen erlaubt
- Pragmatisch sein

----

# Releases

## Ork.1.t7.o12.m3

## 1.1 Ork

## 1.2 Ork

## 2.1 Mage
## 2.2 Mage
## 2.3 Mage

## 3.0 Dragon

## 22.06 Moon
## 22.07 Moon
## 22.07 Moon
## 22.07 Moon
## 22.09 Moon

## 22:07 Moon

## 1 Butterfly
## 2 Butterfly
## 3 Wasp
## 4 Wasp
## 5 Wasp
## 6 Gummibear
## 7 Grizzly
## 8 Grizzly

---

1. main.patch animal
2. animal.patch
3. YY:MM animal.patch
4. YY:MM.patch animal
5. counter animal

### Breaking changes & Compatibility

You have a breaking change if upgrading from version

- Tobira ≤ 5
- Compatible Opencast Tobira API 12-15
- MeiliSearch ≤ 3