-
-
Notifications
You must be signed in to change notification settings - Fork 2.8k
docs: add rfc changelog system replacement #11073
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
wmontwe
wants to merge
5
commits into
thunderbird:main
Choose a base branch
from
wmontwe:docs-add-rfc-changelog-system-replacement
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+672
−0
Open
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
888053f
docs(rfc): add proposal for changelog system replacement
wmontwe dc3992c
docs(technical-design): add technical design for changelog system rep…
wmontwe f951fde
docs: update changelog asset design
wmontwe 5b7ab9e
docs: add changelog asset tree overview
wmontwe 2f2d749
docs: link changelog design to milestone issue
wmontwe File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or 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
95 changes: 95 additions & 0 deletions
95
docs/engineering/rfcs/0001-changelog-system-replacement.md
This file contains hidden or 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,95 @@ | ||
| # RFC 0001: Changelog System Replacement | ||
|
|
||
| * Issue: [#11079](https://github.com/thunderbird/thunderbird-android/issues/11079) | ||
| * Technical design: [Changelog System Replacement](../technical-designs/0001-changelog-system-replacement.md) | ||
| * Status: **Proposed** | ||
|
|
||
| ## Summary | ||
|
|
||
| Replace the current `ckChangeLog` based in-app changelog with a project-owned changelog system. | ||
|
|
||
| The replacement will keep changelog data in generated, schema-validated JSON assets that are packaged with each app | ||
| target. The app will read a generated index and the referenced release-note assets at runtime while preserving the | ||
| existing Changelog screen and Recent Changes behavior. | ||
|
|
||
| ## Motivation | ||
|
|
||
| The current implementation depends on `ckChangeLog`, which is no longer a dependency the project wants to keep for | ||
| in-app changelog behavior. | ||
|
|
||
| The current XML-based flow also leaves important behavior implicit. The app has to interpret changelog text at runtime | ||
| and infer categories from prose. That makes release-note generation, Android runtime behavior, and historical migration | ||
| harder to validate. | ||
|
|
||
| The project should own the changelog data format, validate generated output before packaging, and keep runtime behavior | ||
| simple and predictable. | ||
|
|
||
| ## Proposal | ||
|
|
||
| Adopt a project-owned changelog format and runtime reader: | ||
|
|
||
| * Generate one changelog index file per app target and one JSON file per release. | ||
| * Validate generated and migrated changelog JSON against repository-owned schemas. | ||
| * Migrate existing XML changelog history into the JSON format. | ||
| * Move K-9 Mail changelog resources from the legacy shared `src/main` location to app-target source sets. | ||
| * Update the changelog feature to read the packaged index and release JSON assets instead of `ckChangeLog`. | ||
| * Preserve the existing Changelog and Recent Changes user experiences. | ||
| * Remove the `ckChangeLog` dependency after the replacement is complete. | ||
|
|
||
| The v1 format includes the metadata needed to generate and display the packaged in-app changelog: release identity, | ||
| release ordering, note text, note type, app-specific filtering, feature flag filtering, and issue or pull request | ||
| references. | ||
|
|
||
| Detailed schema fields, release tooling changes, XML migration, runtime behavior, rollout order, and verification belong | ||
| in the linked technical design. | ||
|
|
||
| ## Alternatives Considered | ||
|
|
||
| ### Keep `ckChangeLog` | ||
|
|
||
| This has the lowest short-term implementation cost. | ||
|
|
||
| This is not preferred because it is not maintained anymore and preserves the legacy XML flow. | ||
|
|
||
| ### Keep XML and replace only the runtime parser | ||
|
|
||
| This removes the dependency but keeps the legacy xml artifact. | ||
|
|
||
| This is not preferred because the project still would not have a clear schema for generated changelogs. It also keeps the | ||
| app close to the current text-inference model instead of making note type explicit. | ||
|
|
||
| ### Generate one aggregate file per target | ||
|
|
||
| This would keep runtime loading and validation simple because the app would read a single JSON resource. | ||
|
|
||
| This is not preferred because Thunderbird for Android and K-9 Mail have more than 15 years of changelog history, and | ||
| the existing changelog has required repeated pruning. A single packaged changelog file would recreate the same growth | ||
| pressure over time. | ||
|
|
||
| It would also differ from `thunderbird-notes`, where release notes are maintained as one file per release. | ||
|
|
||
| ### Fetch changelog data at runtime | ||
|
|
||
| This would allow changelog changes without a new app release. | ||
|
|
||
| This is not preferred for this replacement. It would require hosted changelog infrastructure, a network endpoint, app-side | ||
| fetching and failure handling, and a data privacy declaration for the network access. The goal is to replace the packaged | ||
| in-app changelog implementation, not to introduce a network-delivered changelog service. | ||
|
|
||
| ## Risks & Drawbacks | ||
|
|
||
| * Historical XML migration may classify some old entries differently than manual review would. | ||
| * If previous `ckChangeLog` seen state is not migrated, some existing users may see Recent Changes once after upgrade. | ||
| * The change touches release tooling and app runtime code, so it should be delivered in small reviewable steps. | ||
| * Generated assets can become stale if release documentation does not make the new JSON step explicit. | ||
|
|
||
| ## Open Questions | ||
|
|
||
| * Should existing `ckChangeLog` seen state be migrated, or is one possible extra Recent Changes prompt acceptable? | ||
| * Which historical XML files and source branches must be migrated before `ckChangeLog` can be removed? | ||
|
|
||
| ## Outcome | ||
|
|
||
| Filled in when the RFC is accepted, rejected, or superseded. | ||
|
|
||
| If accepted, implementation follows the linked technical design. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.