1
0
mirror of https://github.com/qTox/qTox.git synced 2024-03-22 14:00:36 +08:00
qTox/MAINTAINING.md

275 lines
11 KiB
Markdown
Raw Normal View History

**Guidelines, overview of maintenance process, etc.**
*“Thou shall GPG-sign.”*
# Git config
## GPG signing
While contributors are suggested to use GPG, as a maintainer you **are
required** to use GPG to sign commits & merges.
If you don't have GPG signing set up yet, now is the moment to do it.
[Config, etc.](/CONTRIBUTING.md#git-config)
## SSH
Preferably use SSH.
There are quite a few articles about that:
https://help.github.com/categories/ssh/
## Useful aliases
Check whether commits are GPG-signed with `git logs`
```
git config --global alias.logs 'log --show-signature'
```
# Commits
- **always** use [commit message format]
- **always** GPG-sign your commits.
- it's preferable to make a PR with changes that you're about to commit.
Yes, there might be a situation where something has to be fixed "right now"
on master..
Perhaps a security fix, who knows what future holds. If it's not *that*
important, you're still better off making a PR. Even when you'll just
fast-forward commits from PR onto the `master` branch.
Reasoning for it is that it's always hard to catch bugs/mistakes that you
create, while someone else who just briefly looked at the changeset possibly
can see a problem `:)`
# Pull requests
- **do not** push any `Merge`, `Squash & Merge`, etc. buttons on the website!
The only allowed way of merging is locally, since otherwise merge will not
be signed, and websites can fairly well mess things up.
- **always** test PR that is being merged.
- **always** GPG-sign PR that you're merging.
Commits that are about to be merged don't have to be signed, but the
merge-commit **must** be signed. To simplify the process, and ensure that
things are done "right", it's preferable to use the [`merge-pr.sh`] script,
which does that for you automatically.
- **use** [`merge-pr.sh`] script to merge PRs. First checkout the target
branch, usually either `master` or a release dev branch e.g. `v1.17-dev`,
make sure it's up to date with qTox/qTox, then e.g. `./merge-pr.sh 1234`.
You don't have to use it, but then you're running into risk of breaking
travis build of master & other PRs, since it verifies all commit messages,
indlucing merge messages.
Risk, that can be avoided when one doesn't type manually merge message :wink:
- **might want** to use [`test-pr.sh`].
- give a PR some "breathing space" right after it's created i.e. merging
something right away can lead to bugs & regressions suddenly popping up, thus
it's preferable to wait at least a day or so, to let people test & comment on
the PR before merging.
- with trivial changes, like fixing typos or something along those lines,
feel free to merge right away.
- if a PR requires some changes, comment what parts need to be adjusted,
preferably by using the `Reviewable` button on the first comment.
- if PR doesn't apply properly on top of current master (when using
[`merge-pr.sh`] script), request a rebase
- if a PR requires changes but there has been no activity from the PR submitter
for more than 2 months, close the PR.
# Continous Integration
qTox nightly builds can be found in [qTox-nightly-release]. Should one build
fail, it is important to restart the whole Travis CI build and not just a
single job. The tool managing the nightly builds deletes all build artifacts
on any job failure, so all need to be rebuilt.
# Issues
## Tagging Issues
- When you request more info to be provided in the issue, tag it with
`O-need-info`. Remove tag once the needed info has been provided.
- If the needed information is not provided after 30 days, add the `O-stale`
tag and a comment requesting the information again.
- If the `O-stale` tag is present for more than 30 day, the issue should
be closed.
- If you're going to fix the issue, assign yourself to it.
- when closing an issue, preferably state the reason why it was closed, unless
it was closed automatically by commit message.
- When issue is a duplicate, close the issue with less useful information and
comment the link to the other issue.
## Determining Priority
The priority of an issue should be determined by taking into account the user
impact and how hard it is to fix the issue.
### User impact
We have two labels to rate user impact `U-high` and `U-low`.
Use `U-high` if
- Many users have reported this issue
- The problem is triggered often during typical use of qTox
- The problem causes data loss
- There is no workaround
Use `U-low` if
- Few users reported this problem
- The problem occurs very sporadically
- The problem needs a very specific set of conditions to appear
- There is a workaround
- The problem appears only after multiple days of usage
### Difficulty to fix
We have two labels to estimate the difficulty of a fix, `D-easy` and `D-hard`.
Use `D-easy` if you think that:
- The issue is well described
- The issue can be consistently reproduced
- The issue needs no specific equipment to fix, e.g. specific OS, webcam,...
- The code that causes the problem is known
Use `D-hard` if you think that:
- The issue is described only vaguely
- The exact way to reproduce the issue is not known
- The issue happens only on a specifc OS
- The issue is not only caused by code from qTox
### Determining initial priority
After assesing the user impact and the difficulty to fix the issue you look up
the initial priority for the issue in the following table:
| | `U-high` | `U-low` |
|----------|------------|------------|
| `E-easy` | `P-high` | `P-medium` |
| `E-hard` | `P-medium` | `P-low` |
Possible security issues should be tagged with `P-high` initally. If they are
confirmed security issues, the tag should be changed to `P-very-high`, else
apply the normal rating process.
# Translations from Weblate
Weblate provides an easy way for people to translate qTox. On one hand, it does
require a bit more attention & regular checking whether there are new
translations, on the other, it lessened problems that were happening with
"manual" way of providing translations.
To get translations into qTox:
1. Go to `https://hosted.weblate.org/projects/tox/qtox/#repository` and lock
the repository for translations.
2. Make sure you have git setup to automatically gpg sign commits.
3. To update translated strings from Weblate, in the root of the qTox
repository execute the script `tools/update-weblate.sh`
4. If a new translation language has been added, update the following files:
- `translations/CMakeLists.txt`
- `src/widget/form/settings/generalform.cpp`
- `translations/README.md`
- `translations/i18n.pri`
- `translations/translations.qrc`
5. To update translatable strings from qTox for Weblate, run
`./tools/update-translation-files.sh ALL`
6. Checkout a new branch with e.g. `git checkout -b update_weblate` and open
a Pull Request for it on Github.
7. After the Pull Request has been merged, `reset` Weblate to master and
unlock it.
# Releases
## Tagging scheme
- tag versions that are to be released, make sure that they are GPG-signed,
i.e. `git tag -s v1.8.0`
- use semantic versions for tags: `vMAJOR.MINOR.PATCH`
- `MAJOR` bump version when there are breaking changes to video, audio,
text chats, groupchats, file transfers, and any other basic functionality.
For other things, `MINOR` and `PATCH` are to be bumped.
- `MINOR` bump version when there are:
- new features added
- UI/feature breaking changes
- other non-breaking changes
- `PATCH` bump when there have been only fixes added. If changes include
something more than just bugfixes, bump `MAJOR` or `MINOR` version
accordingly.
- bumping a higher-level version "resets" lower-version numbers, e.g.
`v1.7.1 → v2.0.0`
## Steps for release
### Before tagging
- Format all code using the [`./tools/format-code.sh`] script
chore(CI): Use docker for CI scripts Motiviation: * Reproducing issues in CI is currently difficult * Predicting issues in CI is currently difficult if you are not on ubuntu 18.04 * Reproducing issues submitted from other distros is currently done by creating a VM of that distro and building qtox for it locally * Documentation for how to build on different distros is out of date * Issues on non-ubuntu distributions are not caught by CI * Cross compiling for windows locally is not trivial * Iterating when working with custom build scripts is slow, scripts don't necessarily support re-running without re-starting the docker container and re-building qtox again * Updating dependencies is a pain Changes: * docker-compose file has been added to the root of our repo. After `docker compose run --rm ubuntu` (or other supported distros), you are ready to compile and run qtox * Dependencies are owned by dependency install scripts in buildscripts/. This allows us to use the same exact dependencies in our OSX/windows/linux scripts * New docker images have been added for a variety of distributions. These are now run in CI in a variety of configurations * Docker images are cached in CI so rebuild time for the majority of jobs is quite quick * Build scripts have been trimmed to leverage state of docker containers. * Windows build script no longer installs anything, dependencies are now managed by the windows_builder docker images * Build scripts should now be easily re-runnable. Usage is now `docker compose run --rm <image>` and then run the scripts * All artifacts are now uploaded to github after build, this means we can take an appimage/flatpak/exe/dmg for any given PR and try it out without having to build it ourselves Notes: * Docker image size is quite important. We have a maximum of 5GB cache space on github actions. The majority of the linux distro docker images cache at ~300-400MB, which gives us room to test ~6 distros after accounting for the sizes of flatpak/windows docker images * Docker layer ordering is relatively intentional. Approximate order should be that large dependencies that change infrequently should be farther up. This lowers the amount of rebuilding we have to do when dependencies are updated * download_xxx.sh scripts are the cleanest way I could find to implement a shared dependency map between osx scripts and docker containers. Although it would be nice to have a single dependency mapping file, splitting it into individual scripts allows us to only rebuild some docker layers when dependencies are updated. * Github actions are split between docker image building and docker image use. This allows us to re-use the same docker images for multiple jobs, but only build it once * Unfortunately I could not find a way to de-duplicate the stitching between jobs, so we have a lot of copy pasta in that area
2021-11-08 13:27:45 +08:00
- Update the Flatpak manifest of our [Flathub repository] with the script in flatpak/update_flathub_descriptor_dependencies.py
- Make sure to check if new dependencies need to be added, add them if necessary
- Update version number for windows/osx packages using the
[`./tools/update-versions.sh`] script, e.g. `./tools/update-versions.sh
1.11.0`
- Update toxcore version number to the latest tag in [`./buildscripts/download/download_toxcore.sh]
- Update the bootstrap nodelist at `./res/nodes.json` from https://nodes.tox.chat/json.
This can be done by running [`./tools/update-nodes.sh`]
- Generate changelog with `clog`.
- In a `MAJOR`/`MINOR` release tag should include information that changelog
is located in the `CHANGELOG.md` file, e.g. `For details see CHANGELOG.md`
- To release a `PATCH` version after non-fix changes have landed on `master`
branch, checkout latest `MAJOR`/`MINOR` version and `git cherry-pick -x`
commits from `master` that you want `PATCH` release to include. Once
cherry-picking has been done, tag HEAD of the branch.
- When making a `PATCH` tag, include in tag message short summary of what the
tag release fixes, and to whom it's interesting (often only some
OSes/distributions would find given `PATCH` release interesting).
### After tagging
- Create and GPG-sign the tar.lz and tar.gz archives using
[`./tools/create-tarballs.sh`] script, and upload both archives plus both
signature files to the github release that was created by a Travis OSX
release job.
- Download the binaries that are part of the draft release, sign them in
in detached and ascii armored mode, e.g. `gpg -a -b <artifact>`, and upload
the signatures to the draft release.
- Add a title and description to the draft release, then publish the release.
- Update download links on https://tox.chat to point to the new release.
- Write a short blog post for https://github.com/qTox/blog/ and advertise the
post on Tox IRC channels, popular Tox groups, reddit, or whatever other platforms.
- Merge [`./flatpak/io.github.qtox.qTox.json`] into the manifest of our
[Flathub repository]. Keep the [Flathub repository]'s version of "sources" for
qTox.
- After the build passed for qTox on all architectures on
[the Flathub build bot], merge the PR into the master branch of our
[Flathub repository].
# How to become a maintainer?
Contribute, review & test pull requests, be active, oh and don't forget to
mention that you would want to become a maintainer :P
Aside from contents of [`CONTRIBUTING.md`] you should also know the contents of
this file.
Once you're confident about your knowledge and you've been around the project
helping for a while, ask to be added to the `qTox` organization on GitHub.
[commit message format]: /CONTRIBUTING.md#commit-message-format
[`CONTRIBUTING.md`]: /CONTRIBUTING.md
[`merge-pr.sh`]: /merge-pr.sh
[`test-pr.sh`]: /test-pr.sh
[`./tools/deweblate-translation-file.sh`]: /tools/deweblate-translation-file.sh
[`./tools/create-tarball.sh`]: /tools/create-tarball.sh
[`./tools/update-nodes.sh`]: /tools/update-nodes.sh
[`./tools/update-versions.sh`]: /tools/update-versions.sh
[`./tools/format-code.sh`]: /tools/format-code.sh
[Flathub repository]: https://github.com/flathub/io.github.qtox.qTox
[`./flatpak/io.github.qtox.qTox.json`]: flatpak/io.github.qtox.qTox.json
[the Flathub build bot]: https://flathub.org/builds/#/
[qTox-nightly-release]: https://github.com/qTox/qTox-nightly-releases