Skip to content

Commit f22ee52

Browse files
StypoxStypox
committed
Add instructions for releasing a new version
1 parent badf3d5 commit f22ee52

1 file changed

Lines changed: 208 additions & 0 deletions

File tree

‎src/release.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,209 @@
11
# Making a release
2+
3+
Releasing a new version of Dicio is not only a matter of building and publishing an APK. There are a few things to do beforehand, such as updating the translations, making sure the metadata is correct, preparing a changelog, testing out the app. [^note]
4+
5+
[^note]: This page is partially inspired by [NewPipe's release instructions](https://teamnewpipe.github.io/documentation/07_release_instructions/).
6+
7+
## Preliminary steps
8+
9+
### Permissions
10+
11+
Having the following permissions is required to perform all of the steps outlined in this page, however if you are missing either of them you can ask someone who has them to perform those steps for you.
12+
13+
1. Have admin rights on Weblate
14+
- You should be able to access [Weblate's Maintenance page](https://hosted.weblate.org/projects/dicio-android/#repository)
15+
- Tip: if the correct page does not show up when clicking that URL, make sure you are logged in ;-)
16+
2. Have at least maintainer rights on the dicio-android repo
17+
18+
Steps requiring permission are annotated with [^weblate] or [^repo].
19+
20+
[^weblate]: Requires permissions on Weblate, see [Permissions](#permissions)
21+
22+
[^repo]: Requires permissions on the dicio-android repo, see [Permissions](#permissions)
23+
24+
### Repositories
25+
26+
- Have a cloned Dicio local repository (for the rest of the page, `origin` is assumed to be the remote at `github.com/DicioTeam/dicio-android`)
27+
- Add the `weblate` remote to the same local repository (the URL used below can be found on the Maintenance page on Weblate)
28+
- `git remote add weblate https://hosted.weblate.org/git/dicio-android/strings/`
29+
- Switch to the `main` branch and make sure it is up-to-date with the remote:
30+
- `git checkout main`
31+
- `git pull origin main`
32+
33+
### Version name and conventions
34+
35+
- Find the version code of the next release by looking for `versionCode` in [`app/build.gradle.kts`](https://github.com/DicioTeam/dicio-android/blob/main/app/build.gradle.kts): You will add 1 to that value (from now on called `NEW_VERSION_CODE`) to get the new value (but do not edit the file yet)
36+
- Choose the version number of the next release according to [semantic versioning](https://semver.org/) (from now on called `X.X.X`)
37+
38+
## Merging any remaining PRs
39+
40+
Since releases don't happen too often, it makes sense to merge any Pull Request that is either important (e.g. it provides a fix for a crash) or small (e.g. it just adds some translations), instead of delaying it to the next release cycle. *If you don't have much time available, you can skip this step.*
41+
42+
If you have write access to the repository, then approve and merge the PRs yourself [^repo], otherwise approve them and ask a maintainer to merge them.
43+
44+
## Preparing a changelog
45+
46+
Two changelogs need to be prepared: the GitHub one, with all information, and the F-Droid/PlayStore one, that lists the essential information.
47+
48+
For both changelogs, use these style rules:
49+
- Capitalize the first letter of each item
50+
- Use English verbs as if you were asking someone to do something, so for example use "Fix abc" and not "Fixed abc"; this allows saving a few characters and using a consistent style
51+
- Prepend `[SKILL_NAME]` to the items that have to do with a specific skill
52+
53+
### GitHub changelog
54+
55+
The GitHub changelog is what appears under the [releases page](https://github.com/DicioTeam/dicio-android/releases). Prepare the changelog offline and keep it around for later. It is also possible to [create a draft release](https://github.com/DicioTeam/dicio-android/releases/new) on GitHub [^repo].
56+
57+
- Use the following structure:
58+
```md
59+
### New
60+
- …
61+
62+
### Improved
63+
- …
64+
65+
### Fixed
66+
- …
67+
68+
### Development
69+
- …
70+
```
71+
- Go through [the commit history](https://github.com/DicioTeam/dicio-android/commits/main/) to find out which pull requests were merged and which other commits happened that could be relevant for a changelog
72+
- List new features, improved features/behaviors, bug fixes, and non-user-facing changes under the corresponding sections (sections with no points can be removed)
73+
- List any new languages that were added in the "New" section
74+
- Append `#1234` to the item(s) that were done in pull request 1234 (there can even be multiple PRs)
75+
- Append `(thanks @USERNAME!)` if `@USERNAME` contributed to a item
76+
77+
For example:
78+
```md
79+
- [Weather] Add new provider #456 (thanks @bestContributor!)
80+
```
81+
or (for a change directly committed)
82+
```md
83+
- Update all dependencies
84+
```
85+
86+
### F-Droid changelog
87+
88+
- Create a new English changelog in the [`fastlane/metadata/android/en-US/changelogs/`](https://github.com/DicioTeam/dicio-android/tree/main/fastlane/metadata/android/en-US/changelogs/) folder
89+
- The file should be named `NEW_VERSION_CODE.txt`, using the new version code found in the [Version name and conventions](#version-name-and-conventions)
90+
- The file should have this structure (sections with no points can be removed):
91+
```txt
92+
New
93+
• ...
94+
95+
Improved
96+
• ...
97+
98+
Fixed
99+
• ...
100+
```
101+
- Make sure you use the `•` for points (it looks nicer than `-`)
102+
- Summarize only the most important changes from the draft release
103+
- Make sure the file size is **at most 500 bytes**, in order to **fit [F-Droid's changelog size limit](https://f-droid.org/en/docs/All_About_Descriptions_Graphics_and_Screenshots/#fastlane-structure) (!)**
104+
- Tip: removing the newline at the end of the file saves 1 byte ;-)
105+
- Commit the file on the `main` branch (try to stick to the provided commit message template)
106+
- `git add fastlane/metadata/android/en-US/changelogs/NEW_VERSION_CODE.txt`
107+
- `git commit -m "Add changelog for vX.X.X (NEW_VERSION_CODE)"`
108+
- If you are an admin of the dicio-android repo, just push the changes to the remote `main`
109+
- `git push origin main` [^repo]
110+
- If you are not an admin, create a pull request normally and ask a maintainer to merge it
111+
112+
## Ensuring metadata is up-to-date
113+
114+
- The app descriptions may list outdated information about supported skills and supported languages.
115+
- The sources of truth are [`SkillHandler.kt`](https://github.com/DicioTeam/dicio-android/blob/main/app/src/main/kotlin/org/stypox/dicio/eval/SkillHandler.kt#L46) for skills and [`language.proto`](https://github.com/DicioTeam/dicio-android/blob/main/app/src/main/proto/language.proto) for languages.
116+
- Check whether both skill and language lists are up-to-date in the [repository's README](https://github.com/DicioTeam/dicio-android/blob/main/README.md) and in [Fastlane's English metadata](https://github.com/DicioTeam/dicio-android/blob/main/fastlane/metadata/android/en-US/full_description.txt).
117+
- Make any changes needed to bring them up-to-date, and again either push directly to `main` [^repo] or open a pull request
118+
119+
## Testing for regressions
120+
121+
Before releasing, you should check whether there are any regressions, i.e. new bugs or crashes that were not there in the previous version, *not* bugs that were already known or present in previous versions.
122+
123+
- Build and run the app on your physical phone e.g. using Android Studio or downloading the latest debug APK built by [Continuous Integration](https://github.com/DicioTeam/dicio-android/actions/workflows/ci.yml?query=branch%3Amain) on the `main` branch.
124+
- Try to use the app in many ways and see if anything goes wrong (e.g. try to use every skill, try using STT and TTS, try to switch language, etc.).
125+
- If you find a regression that is either impactful (e.g. app crashes on an important feature) or simple to fix (e.g. a missing null check), open a pull request for it.
126+
- Otherwise, document the regression in a GitHub issue. If it's easy to determine who the author of the regression was, ping them and ask them to provide a fix.
127+
- The release should be delayed if there are significant regressions that need to be fixed, otherwise they risk becoming permanently part of the codebase.
128+
129+
## Pulling translations from Weblate
130+
131+
Do this as one of the last steps before release, to incorporate as many translations as possible.
132+
133+
### Prepare Weblate <small>[^weblate]</small>
134+
135+
1. Go to [Weblate's Maintenance tab](https://hosted.weblate.org/projects/dicio-android/#repository)
136+
2. Press the *Lock* button to prevent translators from translating while you are creating commits; remember to *Unlock* later!
137+
3. Press the *Update* button to update Weblate with the latest changes on dicio-android's `main` branch
138+
4. Press the *Commit* button, if needed, to make sure Weblate creates a commit for translations which have not been committed yet
139+
140+
### Pull changes
141+
142+
Now go **back to the local git repository**:
143+
144+
5. In case you followed these steps before, delete the `weblate-main` branch
145+
- `git branch -D weblate-main`
146+
6. Fetch new changes from the `weblate` remote
147+
- `git fetch weblate`
148+
7. Create a new branch starting from `weblate/main`, named `weblate-main`, and switch to it
149+
- `git checkout -b weblate-main weblate/main`
150+
8. If you run `git log --oneline --graph` you should see a Weblate commit on top, and then all of the commits currently on the `main` branch:
151+
```md
152+
* cmt12hash (HEAD -> weblate-main, weblate/main) Translated using Weblate (...)
153+
* cmt89hash (origin/main, main) Commit message ...
154+
```
155+
9. Switch back to the `main` branch
156+
- `git checkout main`
157+
10. Merge `weblate-main` into `main`:
158+
- `git merge weblate-main`
159+
11. If you are an admin of the dicio-android repo, just push the changes to the remote `main`
160+
- `git push origin main` [^repo]
161+
- If you are not an admin, create a pull request normally and ask a maintainer to merge it
162+
163+
Note that we had to do this process on dicio-android's `main` branch because:
164+
- Weblate's components are connected to dicio-android's `main` branch, and will update changes from there
165+
- Weblate's git repo is not writable, so there is no way to push commits there manually
166+
167+
### Update Weblate <small>[^weblate]</small>
168+
169+
12. Go back to [Weblate's Maintenance tab](https://hosted.weblate.org/projects/dicio-android/#repository)
170+
13. Press the *Update* button to update Weblate with the commit you just pushed on dicio-android's `main` branch
171+
14. **Press the *Unlock*** button to allow translators to translate the changelog and possibly other components (**do not forget this step!**)
172+
173+
## Finally releasing
174+
175+
### Update version numbers
176+
177+
- Edit the [`app/build.gradle.kts`](https://github.com/DicioTeam/dicio-android/blob/main/app/build.gradle.kts) file to bump the release
178+
- Set `versionCode` to `NEW_VERSION_CODE`, i.e. increment the value by 1 as described in [Version name and conventions](#version-name-and-conventions)
179+
- Set `versionName` to `"X.X.X"`
180+
- Commit the version bump (try to stick to the provided commit message template)
181+
- `git add app/build.gradle.kts`
182+
- `git commit -m "Release vX.X.X (NEW_VERSION_CODE)"`
183+
- If you are an admin of the dicio-android repo, just push the changes to the remote `main`
184+
- `git push origin main` [^repo]
185+
- If you are not an admin, create a pull request normally and ask a maintainer to merge it
186+
187+
### Creating a GitHub release <small>[^repo]</small>
188+
189+
- Run the ["Build and create release"](https://github.com/DicioTeam/dicio-android/actions/workflows/build_and_create_release.yml) workflow using the "Run workflow" button (make sure to select `main` as the branch). This will create a draft release, which you can find [here](https://github.com/DicioTeam/dicio-android/releases).
190+
- Download the signed APK from the draft release, and make sure it installs properly on your device as an update.
191+
- Insert the GitHub changelog you [prepared earlier](#github-changelog) into the draft release body.
192+
- Make sure `vX.X.X` is set as the tag name
193+
- Make sure `vX.X.X` is set as the release title
194+
- Make sure `main` is set as the "Target:" branch
195+
- Publish the release
196+
197+
### Creating an F-Droid release
198+
199+
<sup>The store listing is [here](https://f-droid.org/packages/org.stypox.dicio/).</sup>
200+
No manual steps are needed to push the update to F-Droid, since [the metadata](https://gitlab.com/fdroid/fdroiddata/-/blob/master/metadata/org.stypox.dicio.yml) is setup to update automatically after a new `git` tag is created (which happens when pushing the "Release" button of a GitHub release).
201+
One thing to look out for, however, is whether the build is reproducible. See [#308](https://github.com/DicioTeam/dicio-android/issues/308).
202+
203+
### Creating a Play Store release <small>[^repo]</small>
204+
205+
<sup>The store listing is [here](https://play.google.com/store/apps/details?id=org.stypox.dicio).</sup>
206+
*Note: the Play Store release is lower priority, so even if something blocks it (e.g. some new Google requirement), it's fine.*
207+
208+
- Run the ["Publish to Play Store"](https://github.com/DicioTeam/dicio-android/actions/workflows/publish_to_play_store.yml) workflow using the "Run workflow" button (make sure to select `main` as the branch).[^repo]
209+
- Ask @Stypox to complete the release on Google Play Console

0 commit comments

Comments
 (0)