Skip to content
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

doc: document branching and releasing #554

Merged
merged 3 commits into from
Oct 22, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/workflows/codeql-analysis.yml
Original file line number Diff line number Diff line change
@@ -9,12 +9,14 @@ name: "CodeQL"

on:
push:
branches: [ "master", "release/**" ]
branches:
- "master"
- "release/**"

jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest
runs-on: ubuntu-20.04

strategy:
fail-fast: false
1 change: 1 addition & 0 deletions .github/workflows/coverage.yml
Original file line number Diff line number Diff line change
@@ -5,6 +5,7 @@ on:
push:
branches:
- "master"
- "release/**"
jobs:
test:
runs-on: ubuntu-20.04
4 changes: 1 addition & 3 deletions .github/workflows/debianrepo.yml
Original file line number Diff line number Diff line change
@@ -3,10 +3,8 @@ name: debianrepo
on:
push:
branches:
- "stable"
- "release/**"
- "master"
- "debianrepo"
- "release/**"

jobs:
test_386:
42 changes: 23 additions & 19 deletions CLI/linux/pkgdebian
Original file line number Diff line number Diff line change
@@ -7,8 +7,9 @@
# 1. the `ooniprobe` we are packaging is available at
# this path `./CLI/linux/$GOARCH/ooniprobe`;
#
# 2. we are running on a debian system that has the same
# architecture of the `ooniprobe` we are packaging.
# 2. we are running on a debian system that is capable
# of running binaries for the architecture that we wanna
# package, either natively or via qemu-user-static.

if [ $# -ne 1 ] && [ $# -ne 2 ]; then
echo "usage: $0 {arch} [run_number]" 1>&2
@@ -31,9 +32,28 @@ if [ -n "$run_number" ]; then
version="${version}~${run_number}"
fi

darch=""
case $goarch in
386)
darch="i386"
;;
amd64)
darch="amd64"
;;
arm)
darch="armhf"
;;
arm64)
darch="arm64"
;;
esac
echo "Building for GOARCH=$goarch / DEBARCH=$darch"

# The OONI_DEB_DRY_RUN is a semi-undocumented feature allowing
# us to see the commands that would be run by this script.

$OONI_DEB_DRY_RUN dpkg --add-architecture $darch

# install the dependencies required by the build process
$OONI_DEB_DRY_RUN apt-get update -q
$OONI_DEB_DRY_RUN apt-get build-dep -y --no-install-recommends .
@@ -42,7 +62,7 @@ $OONI_DEB_DRY_RUN apt-get build-dep -y --no-install-recommends .
$OONI_DEB_DRY_RUN cp ./debian/changelog ./debian/changelog.oocopy

$OONI_DEB_DRY_RUN dch -v "$version" "New version ${version}"
$OONI_DEB_DRY_RUN dpkg-buildpackage -us -uc -b
$OONI_DEB_DRY_RUN dpkg-buildpackage -a $darch -us -uc -b

# restore the original changelog file
$OONI_DEB_DRY_RUN mv ./debian/changelog.oocopy ./debian/changelog
@@ -51,22 +71,6 @@ $OONI_DEB_DRY_RUN mv ./debian/changelog.oocopy ./debian/changelog
# of it when using a build container
$OONI_DEB_DRY_RUN mv ../*.deb .

darch=""
case $goarch in
386)
darch="i386"
;;
amd64)
darch="amd64"
;;
arm)
darch="armhf"
;;
arm64)
darch="arm64"
;;
esac

# install the package on the container as a smoke test to
# ensure that it is installable.
DEBIAN_FRONTEND=noninteractive dpkg -i "ooniprobe-cli_${version}_${darch}.deb"
62 changes: 50 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -81,16 +81,54 @@ https://github.com/ooni/spec) repository. If the spec is missing,
please help the pull request reviewer to create it. If the spec is
not clear, please let us know during the review.

When you write a new experiment, keep the measurement phase and the
results analysis phases as separate functions. This helps us a lot
to write better unit tests for our code.
To get a sense of what we expect from an experiment, see the [internal/tutorial](
https://github.com/ooni/probe-cli/tree/master/internal/tutorial) tutorial

## Branching and releasing

The following diagram illustrates the overall branching and releasing
strategy loosely followed by the core team. If you are an external
contributor, you generally only care about the development part, which
is on the left-hand side of the diagram.

![branching and releasing](docs/branching.png)

Development uses the `master` branch. When we need to implement a
feature or fix a bug, we branch off of the `master` branch. We squash
and merge to include a feature or fix branch back into `master`.

We periodically tag `-alpha` releases directly on `master`. The
semantics of such releases is that we reached a point where we have
features we would like to test using the `miniooni` research CLI
client. As part of these releases, we also update dependencies and
embedded assets. This process ensures that we perform better testing
of dependencies and assets as part of development.

The `master` branch and pull requests only run CI lightweight tests
that ensure the code still compiles, has good coverage, and we are
not introducing regressions in terms of the measurement engine.

To draft a release we branch off of `master` and create a `release/x.y`
branch where `x` is the major number and `y` is the minor number. For
release branches, we enable a very comprehensive set of tests that run
automatically with every commit. The purpose of a release branch is to
make sure all checks are green and hotfix bugs that we may discover
as part of more extensively testing a release candidate. Beta and stable
releases should occur on this branch. Subsequent patch releases should
also occur on this branch. We have one such branch for each `x.y`
release. If there are fixes on `master` that we want to backport, we
cherry-pick them into the release branch. Likewise, if we need to
forward port fixes, we cherry-pick them into `master`.

When we branch off release `x.y` from `master`, we also need to bump
the `alpha` version used by `master`.

None of the branches described so far automatically publishes any
binary package. To publish binary packages we use the `PRODUCT-staging`
branches (e.g., `mobile-staging`). To trigger these builds, we merge
from a release branch into the desired `PRODUCT-staging` branch. This
design ensures that we only publish binary packages when we want to
do so. Because we merge from a release branch, we are not pushing alpha
code to binary releases. (The only exception to this rule is `miniooni`,
treated differently because it's an `alpha` client.)

To get a sense of what we expect from an experiment, see:

- the internal/engine/experiment/example experiment

- the internal/engine/experiment/webconnectivity experiment

- the [internal/tutorial](https://github.com/ooni/probe-cli/tree/master/internal/tutorial) tutorial

Thank you!
12 changes: 12 additions & 0 deletions debian/rules
Original file line number Diff line number Diff line change
@@ -14,5 +14,17 @@ override_dh_auto_build:
override_dh_dwz:
true

override_dh_strip:
# We cross compile and build packages for any arch from
# linux/amd64 so we need to avoid this step. BTW this step
# is not needed because we already strip when building.
true

override_dh_makeshlibs:
# We cross compile and build packages for any arch from
# linux/amd64 so we need to avoid this step. BTW this step
# is not needed because we don't have any shlib.
true

override_dh_auto_install:
dh_auto_install -- --no-source
Loading