feat: add full Zonemaster stack with Docker and Spanish UI
- Clone all 5 Zonemaster component repos (LDNS, Engine, CLI, Backend, GUI) - Dockerfile.backend: 8-stage multi-stage build LDNS→Engine→CLI→Backend - Dockerfile.gui: Astro static build served via nginx - docker-compose.yml: backend (internal) + frontend (port 5353) - nginx.conf: root redirects to /es/, /api/ proxied to backend - zonemaster-gui/config.ts: defaultLanguage set to 'es' (Spanish) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
97
zonemaster/docs/internal/maintenance/ChangeManagement.md
Normal file
97
zonemaster/docs/internal/maintenance/ChangeManagement.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Zonemaster - Change management
|
||||
|
||||
## Scope
|
||||
|
||||
This document outlines how the any changes to the software during the
|
||||
technical maintenance period will be classified and the process to implement
|
||||
these changes.
|
||||
|
||||
## Input for change
|
||||
|
||||
Change requests can come from anywhere such as the users mailinglist, the
|
||||
steering committee or the development team. The change requests could be
|
||||
classified into two broad categories:
|
||||
|
||||
1. Minor change
|
||||
2. Major change
|
||||
|
||||
## Minor change
|
||||
|
||||
The nature of minor change requests are explained in the following
|
||||
subsection:
|
||||
|
||||
### Bug Fixing
|
||||
|
||||
Any bug fixes, the team or any user discovers should be published in the
|
||||
GitHub issue tracker.
|
||||
|
||||
Not all issues in the tracker are bugs, and not all reported bugs are
|
||||
software bugs, but can be protocol errors in DNS, or user or documentation
|
||||
errors.
|
||||
|
||||
Bug fixes are included in minor releases. See the [version numbering policy]
|
||||
document for documentation on version numbers for releases.
|
||||
|
||||
### Minor Changes
|
||||
|
||||
Minor changes are new features, changes or deprecated functionality that
|
||||
do not break backwards compatibility, neither force any user to change or
|
||||
update their environment that currently runs the software.
|
||||
|
||||
Minor changes are included in minor releases. See the [version numbering policy]
|
||||
document for documentation on version numbers for releases.
|
||||
|
||||
## Major changes
|
||||
|
||||
Any change and specification that requires changes in the software
|
||||
architecture, an API change or new major features could be classified
|
||||
under the category "Major change".
|
||||
|
||||
Major changes are included in major releases. See the [version numbering policy]
|
||||
document for documentation on version numbers for releases.
|
||||
|
||||
## Process to implement the change
|
||||
|
||||
Change requests can come from anywhere such as the users mailinglist, the
|
||||
steering committee or the development team.
|
||||
|
||||
### Minor changes
|
||||
|
||||
A "bug fix" or "minor change" should be added as an issue in GitHub. Then
|
||||
the person corresponding is assigned by the release manager or the person
|
||||
who has created the issue. The assigned person should then close the
|
||||
ticket within a specified time as mentioned in the "Key Performance
|
||||
Indicator" (or) update the bug with the time duration on when the bug/minor improvement could be solved (or) comments the reason for not able to solve
|
||||
the bug/minor improvement.
|
||||
|
||||
### Major changes
|
||||
|
||||
Any new development for Zonemaster must follow the strict process where
|
||||
there are formal requirements, specifications for implementing the
|
||||
requirements and then any design and architecture fulfilling the
|
||||
specifications, and finally the implementation and quality assurance.
|
||||
When all this is performed successfully the software package is released
|
||||
using the release process.
|
||||
|
||||
#### Decision on discarding or including changes
|
||||
|
||||
Whatever be the type of change request, it should go through the "Issues
|
||||
tracker" in the GitHub project. All requests should be promptly responded
|
||||
to, even if the decision to acknowledge the request is postponed (or)
|
||||
not taken into consideration.
|
||||
|
||||
Requirements should then be ranked in importance depending on a number of
|
||||
factors such as complexity, amount of work, risk, architectural changes,
|
||||
relevance to the product and so on.
|
||||
|
||||
The decision to include the requirement for the release during the
|
||||
maintenance period will be taken by the development team in consultation
|
||||
with the steering committee.
|
||||
|
||||
New requirements that are acknowledged (by the development team and the
|
||||
steering committee) make it to the roadmap and planned for specification
|
||||
and implementation. They are also added to the current set of requirements.
|
||||
|
||||
|
||||
|
||||
[version numbering policy]: ../design/Versions%20and%20Releases.md
|
||||
@@ -0,0 +1 @@
|
||||
Moved to [Translating Engine, CLI and Backend](../../public/translation/Translating-Engine-CLI-Backend.md)
|
||||
93
zonemaster/docs/internal/maintenance/IssueLabels.md
Normal file
93
zonemaster/docs/internal/maintenance/IssueLabels.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# Labels for Issues and Pull Requests
|
||||
|
||||
## Label categories
|
||||
|
||||
The table below defines the labels to be used when classifying issues and pull requests.
|
||||
Each label is assigned to one of these categories:
|
||||
|
||||
* Area
|
||||
* Priority
|
||||
* Release category
|
||||
* Status
|
||||
* Type
|
||||
* Versioning
|
||||
|
||||
# Usage
|
||||
|
||||
A label from *Area* and *Type* should be attached to an issue or pull request,
|
||||
when applicable.
|
||||
|
||||
One label from *Priority* could be attached to an issue, or else the issue is
|
||||
considered to have normal priority. Similarly, the same could be done for a pull
|
||||
request.
|
||||
|
||||
A label from *Status* can be used if applicable.
|
||||
|
||||
A PR should always have exactly one label from *Versioning* except in the
|
||||
[Zonemaster/Zonemaster] repository where they do not apply.
|
||||
|
||||
A PR should have one or more labels from *Release category*. `RC-None` must not
|
||||
be combined with any other *Release category* label.
|
||||
|
||||
## Labels
|
||||
|
||||
Category | Label | Color | Used in repository | Scope | Description
|
||||
-----------------|--------------------|---------|--------------------|-------|---------------------------------------------------------
|
||||
Area | A-Documentation | green | all | Both | Area: Documentation only.
|
||||
Area | A-TestCase | green | main or Engine | Both | Area: Test case specification or implementation of test case.
|
||||
Area | A-Translation | green | all | Both | Area: Documentation of, implementation of or actual translation of text.
|
||||
Priority | P-High | red | all | Both | Priority: Issue to be solved before others.
|
||||
Release category | RC-BreakingChanges | magenta | all | PR | Release category: Breaking changes.
|
||||
Release category | RC-Deprecations | magenta | all | PR | Release category: Deprecations.
|
||||
Release category | RC-Features | magenta | all | PR | Release category: Features.
|
||||
Release category | RC-Fixes | magenta | all | PR | Release category: Fixes.
|
||||
Release category | RC-None | magenta | all | PR | Release category: Not to be included in Changes file.
|
||||
Status | S-ReleaseTested | yellow | all | PR | Status: The PR has been successfully tested in release testing.
|
||||
Status | S-PRforIssue | yellow | all | Issue | Status: There is a PR that is meant to resolve the issue.
|
||||
Type | T-Bug | red | all | Both | Type: Bug in software or error in test case specification.
|
||||
Type | T-Feature | blue | all | Issue | Type: New feature in software or test case specification.
|
||||
Type | T-Question | blue | all | Issue | Type: External question.
|
||||
Type | T-TrackingIssue | blue | all | Issue | Type: Tracks other issues, PRs or other changes.
|
||||
Versioning | V-Major | pink | all but main | Both | Versioning: The change gives an update of major in version.
|
||||
Versioning | V-Minor | pink | all but main | Both | Versioning: The change gives an update of minor in version.
|
||||
Versioning | V-Patch | pink | all but main | Both | Versioning: The change gives an update of patch in version.
|
||||
|
||||
### Color
|
||||
|
||||
In the table above, the following terms for "Color" are defined:
|
||||
|
||||
Term | Color code
|
||||
---------|---------------------------------------------
|
||||
blue | #0CCFF2
|
||||
green | #55D700
|
||||
pink | #FFC0CB
|
||||
red | #EE0701
|
||||
yellow | #FFCE2E
|
||||
magenta | #D4C5F9
|
||||
|
||||
### Used in repository
|
||||
|
||||
In the table above, the following terms for "Used in repository" are defined:
|
||||
|
||||
Term | Definition or meaning
|
||||
---------|---------------------------------------------
|
||||
all | Stands for the [Zonemaster/Zonemaster], [Zonemaster-LDNS], [Zonemaster-Engine], [Zonemaster-CLI], [Zonemaster-Backend] and [Zonemaster-GUI] repositories
|
||||
main | Stands for the [Zonemaster/Zonemaster] repository
|
||||
Engine | Stands for the [Zonemaster-Engine] repository
|
||||
|
||||
### Scope
|
||||
|
||||
In the table above, the following terms for "Scope" are defined:
|
||||
|
||||
Term | Definition or meaning
|
||||
------|---------------------------------------------------
|
||||
PR | The label is meant for Pull Request only
|
||||
Issue | The label is meant for Issue only
|
||||
Both | The label is meant for both Pull Request and Issue
|
||||
|
||||
[Zonemaster/Zonemaster]: https://github.com/zonemaster/zonemaster
|
||||
[Zonemaster-LDNS]: https://github.com/zonemaster/zonemaster-ldns
|
||||
[Zonemaster-Engine]: https://github.com/zonemaster/zonemaster-engine
|
||||
[Zonemaster-CLI]: https://github.com/zonemaster/zonemaster-cli
|
||||
[Zonemaster-Backend]: https://github.com/zonemaster/zonemaster-backend
|
||||
[Zonemaster-GUI]: https://github.com/zonemaster/zonemaster-gui
|
||||
@@ -0,0 +1,364 @@
|
||||
Release Process - Create Docker Image
|
||||
=====================================
|
||||
|
||||
## Table of contents
|
||||
|
||||
* [1. Overview](#1-overview)
|
||||
* [2. Prerequisite](#2-prerequisite)
|
||||
* [3. Create Docker images](#3-create-docker-images)
|
||||
* [4. Upload images to Docker Hub](#4-upload-images-to-docker-hub)
|
||||
* [5. Image sanity checks][sanity checks]
|
||||
* [6. Handy Docker commands][Handy Docker commands]
|
||||
|
||||
## 1. Overview
|
||||
|
||||
This document covers two stages in the release processes:
|
||||
|
||||
1. Creating Docker images for testing.
|
||||
2. Creating Docker image for publishing on Docker Hub
|
||||
|
||||
Presently only Zonemaster-CLI is published, and therefore only Zonemaster-LDNS,
|
||||
Zonemaster-Engine and Zonemaster-CLI are covered here.
|
||||
|
||||
|
||||
## 2. Prerequisite
|
||||
|
||||
### Environment
|
||||
|
||||
The steps in this documents are assumed to be executed on a computer installed
|
||||
as an [Ubuntu Build Environment] computer. It could work on another OS as long
|
||||
as the same support is available.
|
||||
|
||||
All commands in this instruction are assumed to be executed from the one and the
|
||||
same directory. If you run `cd`, then you have to run `cd` back to the start
|
||||
directory.
|
||||
|
||||
The Docker environment is assumed to be clean. Consider running the following
|
||||
commands to clean up before proceeding (see section "[Handy Docker commands]"):
|
||||
```sh
|
||||
[ "$(docker ps -a -q)" != '' ] && docker rm -f $(docker ps -a -q)
|
||||
```
|
||||
```sh
|
||||
[ "$(docker image ls -q)" != '' ] && docker image prune -a
|
||||
```
|
||||
|
||||
### Enable IPv6 support
|
||||
|
||||
Docker has no IPv6 support by default. On Linux it can be enabled. Do that unless
|
||||
already done, or else zonemaster-cli will report errors when trying to access
|
||||
servers on IPv6.
|
||||
|
||||
Create or update `/etc/docker/daemon.json`. This is a minimal file that enables
|
||||
IPv6 support:
|
||||
|
||||
```json
|
||||
{
|
||||
"ipv6": true,
|
||||
"fixed-cidr-v6": "2001:db8:1::/64"
|
||||
}
|
||||
```
|
||||
|
||||
Restart the docker daemon:
|
||||
```sh
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
## 3. Create Docker images
|
||||
|
||||
### Clone the repositories
|
||||
|
||||
```sh
|
||||
git clone https://github.com/zonemaster/zonemaster-ldns
|
||||
git clone https://github.com/zonemaster/zonemaster-engine
|
||||
git clone https://github.com/zonemaster/zonemaster-cli
|
||||
git clone https://github.com/zonemaster/zonemaster-backend
|
||||
```
|
||||
|
||||
### Check out right branch depending on the use case
|
||||
|
||||
* Check out `develop` branch when creating an image for release testing:
|
||||
|
||||
```sh
|
||||
git -C zonemaster-ldns checkout origin/develop
|
||||
git -C zonemaster-engine checkout origin/develop
|
||||
git -C zonemaster-cli checkout origin/develop
|
||||
git -C zonemaster-backend checkout origin/develop
|
||||
```
|
||||
|
||||
* Check out `master` branch when creating an image for Docker Hub at release, or
|
||||
when creating an image based on release version:
|
||||
|
||||
```sh
|
||||
git -C zonemaster-ldns checkout origin/master
|
||||
git -C zonemaster-engine checkout origin/master
|
||||
git -C zonemaster-cli checkout origin/master
|
||||
git -C zonemaster-backend checkout origin/master
|
||||
```
|
||||
|
||||
### Make sure repositories are clean and create `Makefile` in all repositories
|
||||
|
||||
```sh
|
||||
(cd zonemaster-ldns; git submodule deinit -f ldns; git clean -dfx; git reset --hard; perl Makefile.PL)
|
||||
```
|
||||
```sh
|
||||
(cd zonemaster-engine; git clean -dfx; git reset --hard; perl Makefile.PL)
|
||||
```
|
||||
```sh
|
||||
(cd zonemaster-cli; git clean -dfx; git reset --hard; perl Makefile.PL)
|
||||
```
|
||||
```sh
|
||||
(cd zonemaster-backend; git clean -dfx; git reset --hard; perl Makefile.PL)
|
||||
```
|
||||
|
||||
|
||||
### Create images
|
||||
|
||||
Create an image for each repository. That image will be tagged "local". The
|
||||
images must be created in order since there is a dependency on the previous
|
||||
image in each step.
|
||||
```sh
|
||||
make -C zonemaster-ldns all dist docker-build
|
||||
```
|
||||
```sh
|
||||
make -C zonemaster-engine all dist docker-build
|
||||
```
|
||||
```sh
|
||||
make -C zonemaster-cli all dist docker-build
|
||||
```
|
||||
```sh
|
||||
make -C zonemaster-backend all dist docker-build
|
||||
```
|
||||
|
||||
|
||||
### Determine version of Zonemaster-CLI image
|
||||
|
||||
> The description in this section must be followed if the image is to be uploaded
|
||||
> to Docker Hub below. If not, this section can be skipped, modified or followed
|
||||
> depending on needs.
|
||||
|
||||
The version of Zonemaster-CLI has the format "v0.0.0" and it is the normal
|
||||
version of the Docker image too. If needed a "dash version" is used on the Docker
|
||||
images, and that has the format "v0.0.0-N" where "v0.0.0" is the same version as
|
||||
Zonemaster-CLI, and "N" is a positive integer starting with "1".
|
||||
|
||||
First determine what the version should be. Compare the version of
|
||||
Zonemaster-Cli just built with the highest version of the image uploaded to
|
||||
Docker Hub. There are three valid possibilities:
|
||||
|
||||
1. The version on Docker Hub has lower version than the local version. If so
|
||||
set the tags of the image with the simple steps below ignoring "dash
|
||||
versions".
|
||||
|
||||
*Example: version on Docker Hub is v6.0.0 or v6.0.0-1, local version is v6.0.1,
|
||||
new image will have version v6.0.1.*
|
||||
|
||||
2. The version on Docker Hub has the same version as the local version. Set the
|
||||
version on the new Docker image to be "v0.0.0-1" where "v0.0.0" is equal to
|
||||
the local version.
|
||||
|
||||
*Example: version on Docker Hub is v6.0.1, local version is v6.0.1, new image
|
||||
will have version v6.0.1-1.*
|
||||
|
||||
3. The version on Docker Hub is a "dash version" where the "v0.0.0" part is the
|
||||
same as the local version. Set the version of the new Docker image to be
|
||||
"v0.0.0-N" where "v0.0.0" is equal to the local version and "N" is the
|
||||
integer incremented by 1 compared to the version on Docker Hub.
|
||||
|
||||
*Example: version on Docker Hub is v6.0.1-1, local version is v6.0.1, new image
|
||||
will have version v6.0.1-2.*
|
||||
|
||||
### Determine version of Zonemaster-Backend image
|
||||
|
||||
The version of Zonemaster-Backend follows the same rules as Zonemaster-CLI.
|
||||
|
||||
|
||||
### Tag the Zonemaster-CLI image
|
||||
|
||||
For the Zonemaster-CLI image, add a version tag and a tag "latest".
|
||||
|
||||
* Add version tag:
|
||||
```sh
|
||||
make -C zonemaster-cli docker-tag-version
|
||||
```
|
||||
|
||||
* Add tag "latest":
|
||||
```sh
|
||||
make -C zonemaster-cli docker-tag-latest
|
||||
```
|
||||
|
||||
* If "dash version" is to be used, set tag with that version and remove tag with
|
||||
plain version where "v0.0.0" should be the local version and "v0.0.0-N" should be
|
||||
the "dash version" determined above:
|
||||
```
|
||||
cd zonemaster-cli
|
||||
docker tag zonemaster/cli:local zonemaster/cli:v0.0.0-N
|
||||
docker rmi zonemaster/cli:v0.0.0
|
||||
```
|
||||
|
||||
All the created images can now be listed. Also consider doing [sanity checks] to
|
||||
verify that all images work. Images without tag are temporary images without
|
||||
further use. List images:
|
||||
|
||||
```sh
|
||||
docker images
|
||||
```
|
||||
|
||||
|
||||
### Tag the Zonemaster-Backend image
|
||||
|
||||
For the Zonemaster-Backend image, add a version tag and a tag "latest".
|
||||
|
||||
* Add version tag:
|
||||
```sh
|
||||
make -C zonemaster-backend docker-tag-version
|
||||
```
|
||||
|
||||
* Add tag "latest":
|
||||
```sh
|
||||
make -C zonemaster-backend docker-tag-latest
|
||||
```
|
||||
|
||||
* If "dash version" is to be used, set tag with that version and remove tag with
|
||||
plain version where "v0.0.0" should be the local version and "v0.0.0-N" should be
|
||||
the "dash version" determined above:
|
||||
```
|
||||
cd zonemaster-backend
|
||||
docker tag zonemaster/backend:local zonemaster/backend:v0.0.0-N
|
||||
docker rmi zonemaster/backend:v0.0.0
|
||||
```
|
||||
|
||||
All the created images can now be listed. Also consider doing [sanity checks] to
|
||||
verify that all images work. Images without tag are temporary images without
|
||||
further use. List images:
|
||||
|
||||
```sh
|
||||
docker images
|
||||
```
|
||||
|
||||
|
||||
## 4. Upload images to Docker Hub
|
||||
|
||||
To upload an image to the Zonemaster Docker Hub organization you have to have
|
||||
a Docker Hub account and the authorization to upload images.
|
||||
|
||||
```sh
|
||||
docker login
|
||||
```
|
||||
|
||||
The same image is pushed twice with different tags. Verify in the listing
|
||||
above that they have the same ID.
|
||||
|
||||
* Push latest.
|
||||
```sh
|
||||
docker push zonemaster/cli:latest
|
||||
docker push zonemaster/backend:latest
|
||||
```
|
||||
|
||||
* Set correct version (see listing above) and push image with version tag. If
|
||||
"dash version" is used, use "v0.0.0-N" set to correct version instead.
|
||||
```sh
|
||||
docker push zonemaster/cli:v0.0.0
|
||||
docker push zonemaster/backend:v0.0.0
|
||||
```
|
||||
|
||||
## 5. Image sanity checks
|
||||
|
||||
Zonemaster-LDNS:
|
||||
|
||||
```sh
|
||||
docker run --rm zonemaster/ldns:local perl -MZonemaster::LDNS -E 'say Zonemaster::LDNS->new("9.9.9.9")->query("zonemaster.net")->string'
|
||||
```
|
||||
|
||||
Zonemaster-Engine:
|
||||
|
||||
```sh
|
||||
docker run --rm zonemaster/engine:local perl -MZonemaster::Engine -E 'say join "\n", Zonemaster::Engine->test_module("BASIC", "zonemaster.net")'
|
||||
```
|
||||
|
||||
Zonemaster-CLI:
|
||||
|
||||
```sh
|
||||
docker run --rm zonemaster/cli:local zonemaster.net
|
||||
```
|
||||
|
||||
Zonemaster-Backend:
|
||||
|
||||
Start the backend in the background:
|
||||
|
||||
```sh
|
||||
docker run --rm -p 5000:5000 --name zm -d zonemaster/backend:local full
|
||||
```
|
||||
|
||||
Run `docker ps -a`. The container named `zm` should be running.
|
||||
|
||||
Run a test through the backend:
|
||||
```sh
|
||||
docker run -ti --rm --net host zonemaster/backend:local zmtest zonemaster.net
|
||||
```
|
||||
|
||||
The output should be a JSON object containing, among other things,
|
||||
a list of message tags in JSON format.
|
||||
|
||||
Test the correct operation of the `zmb` tool by running a test:
|
||||
```sh
|
||||
docker run -ti --rm --net host zonemaster/backend:local zmb start_domain_test --domain zonemaster.net
|
||||
docker run -ti --rm --net host zonemaster/backend:local zmb get_test_results --test-id be98f37d3b137ce0 --lang en
|
||||
```
|
||||
|
||||
The output should be a JSON object, similar to the previous one.
|
||||
|
||||
Finally, stop the backend:
|
||||
```sh
|
||||
docker stop zm
|
||||
```
|
||||
|
||||
And run `docker ps -a` to ensure that the backend is no longer running.
|
||||
|
||||
|
||||
## 6. Handy Docker commands
|
||||
|
||||
List all containers, including stopped containers.
|
||||
|
||||
```sh
|
||||
docker ps -a
|
||||
```
|
||||
|
||||
List all images
|
||||
```sh
|
||||
docker images
|
||||
```
|
||||
|
||||
Remove container identified as "ID"
|
||||
```sh
|
||||
docker rm ID
|
||||
```
|
||||
|
||||
Remove image identified as "ID"
|
||||
```sh
|
||||
docker rmi ID
|
||||
```
|
||||
|
||||
Remove all containers
|
||||
```sh
|
||||
docker rm -f $(docker ps -a -q)
|
||||
```
|
||||
|
||||
Remove all images
|
||||
```sh
|
||||
docker image prune -a
|
||||
```
|
||||
|
||||
Save an image to a tar file
|
||||
```sh
|
||||
docker save -o docker-zonemaster-cli.tar zonemaster/engine
|
||||
```
|
||||
|
||||
Load an image from a tar file
|
||||
```sh
|
||||
docker load -i docker-zonemaster-cli.tar
|
||||
```
|
||||
|
||||
|
||||
[Ubuntu Build Environment]: ../distrib-testing/Ubuntu-build-environment.md
|
||||
[Sanity checks]: #5-image-sanity-checks
|
||||
[Handy Docker commands]: #6-handy-docker-commands
|
||||
@@ -0,0 +1,168 @@
|
||||
Release process - Create Test Distribution
|
||||
==========================================
|
||||
|
||||
## Table of contents
|
||||
|
||||
* [1. Overview](#1-overview)
|
||||
* [2. Prepare a build environment](#2-prepare-a-build-environment)
|
||||
* [3. Create a clean environment](#3-create-a-clean-environment)
|
||||
* [4. Generate Makefile, META.yml and others](#4-generate-makefile-metayml-and-others)
|
||||
* [5. Verify that MANIFEST is up to date and that tarball can be built](#5-verify-that-manifest-is-up-to-date-and-that-tarball-can-be-built)
|
||||
* [6. Produce distribution tarballs](#6-produce-distribution-tarballs)
|
||||
* [7. Produce distribution zip file](#7-produce-distribution-zip-file)
|
||||
* [8. Produce Docker image](#8-produce-docker-image)
|
||||
* [9. Verify that Zonemaster works when installed](#9-verify-that-zonemaster-works-when-installed)
|
||||
* [10. Restart testing](#10-restart-testing)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The purpose of this part is to create the test distributions that can be
|
||||
used in QA testing for a release. It can also be used to create test
|
||||
distributions to verify a pull request.
|
||||
|
||||
> **Note:** *Normally, the develop branch version of this document should be used.*
|
||||
|
||||
## 2. Prepare a build environment
|
||||
|
||||
Set up build system to be used for the test distribution creation. See
|
||||
[Build Environment Preparation] for how to set it up.
|
||||
|
||||
|
||||
## 3. Create a clean environment
|
||||
|
||||
Make sure that you have checked out the correct git branch, normally
|
||||
the `develop` branch and that your clone is up-to-date.
|
||||
```
|
||||
git fetch --all
|
||||
git branch
|
||||
```
|
||||
For Zonemaster-LDNS only - empty the submodule area (LDNS):
|
||||
|
||||
```
|
||||
git submodule deinit -f ldns
|
||||
```
|
||||
Make sure your working directory is clean.
|
||||
```
|
||||
git status --ignored
|
||||
```
|
||||
To clean (throw away untracked changes or files):
|
||||
```
|
||||
git clean -dfx
|
||||
git reset --hard
|
||||
```
|
||||
You should usually work in the *develop branch*, and that should be up-to-date
|
||||
with the remote *develop branch*. Your working branch:
|
||||
```
|
||||
git branch -av | grep "^*"
|
||||
```
|
||||
All branches called "develop":
|
||||
```
|
||||
git branch -av --list "*develop"
|
||||
```
|
||||
|
||||
## 4. Generate Makefile, META.yml and others
|
||||
|
||||
> This section is not relevant for Zonemaster-GUI.
|
||||
|
||||
* For Zonemaster-LDNS:
|
||||
```
|
||||
perl Makefile.PL --no-ed25519
|
||||
```
|
||||
* For all components except Zonemaster-LDNS:
|
||||
```
|
||||
perl Makefile.PL
|
||||
```
|
||||
> **Note: You can ignore the following warnings:**
|
||||
> * Missing META.yml (created by the very same command).
|
||||
> * Zonemaster-LDNS: Missing ldns source files (fetched by the very same command).
|
||||
> * Zonemaster-Engine and Zonemaster-CLI: Missing .mo files (created in a later step).
|
||||
> * Missing prerequisite (only needed on target system), e.g.:
|
||||
> * "Warning: prerequisite JSON::XS 0 not found."
|
||||
|
||||
## 5. Verify that MANIFEST is up to date and that tarball can be built
|
||||
|
||||
> This section is not relevant for Zonemaster-GUI.
|
||||
|
||||
Build generated files (if any) and verify that a distribution tarball can be
|
||||
successfully built for each component that is to be updated in this release.
|
||||
```
|
||||
make all
|
||||
```
|
||||
For all components, make sure that all files are covered by MANIFEST and/or
|
||||
MANIFEST.SKIP, i.e. no missing or extra files:
|
||||
```
|
||||
make distcheck
|
||||
```
|
||||
|
||||
## 6. Produce distribution tarballs
|
||||
|
||||
> This section is not relevant for Zonemaster-GUI.
|
||||
```
|
||||
make dist
|
||||
```
|
||||
|
||||
## 7. Produce distribution zip file
|
||||
|
||||
> This section is relevant for Zonemaster-GUI only.
|
||||
|
||||
For this you need a [build environment for Node.js], on which you create
|
||||
the zip file.
|
||||
|
||||
Clone the Zonemaster-GUI git repository:
|
||||
|
||||
1. `git clone -b develop https://github.com/zonemaster/zonemaster-gui.git`
|
||||
2. `cd zonemaster-gui`
|
||||
|
||||
If you already have the repository:
|
||||
|
||||
1. `cd zonemaster-gui`
|
||||
2. `git fetch --all`
|
||||
3. `git checkout origin/develop`
|
||||
|
||||
Build the distribution zip file:
|
||||
|
||||
1. `npm install`
|
||||
2. `npm run build`
|
||||
3. `npm run release`
|
||||
|
||||
> If you get building errors, repeat the `nvm` commands in
|
||||
> [build environment for Node.js] first.
|
||||
>
|
||||
> Usually you can ignore warnings and security fixes, and usually you
|
||||
> do not run any `npm audit fix`. Check for open issues in Zonemaster-GUI
|
||||
> and ask the others in the work group.
|
||||
|
||||
The distribution zip file is in the root level of the zonemaster-gui folder.
|
||||
Its name is `zonemaster_web_gui_v0.0.0.zip` with correct version.
|
||||
|
||||
|
||||
## 8. Produce Docker image
|
||||
|
||||
Follow the instructions in [Create Docker Image] to build CLI Docker image for
|
||||
testing.
|
||||
|
||||
## 9. Verify that Zonemaster works when installed
|
||||
|
||||
Verify that Zonemaster works when installed according to the documented
|
||||
installation procedures
|
||||
|
||||
Using the *preliminary distribution tarballs* produced in step 6 above, the
|
||||
*preliminary distribution zip file* produced in step 7 above and the Docker
|
||||
image produced in step 8, follow the procedures in [SystemTesting].
|
||||
|
||||
## 10. Restart testing
|
||||
|
||||
If the system testing fails in a way that requires updated distribution
|
||||
tarballs, zip file or Docker image:
|
||||
1. Get the changes merged.
|
||||
2. Consider whether the actions taken in steps 2–8 above need amendment.
|
||||
3. Resume this document from step 9 above.
|
||||
|
||||
|
||||
[Build Environment Preparation]: ../distrib-testing/README.md
|
||||
[Build environment for Node.js]: ../distrib-testing/Ubuntu-Node.js-build-environment.md
|
||||
[Create Docker Image]: ReleaseProcess-create-docker-image.md
|
||||
[NVM]: https://github.com/nvm-sh/nvm
|
||||
[Node.js]: https://nodejs.org/en/
|
||||
[SystemTesting]: SystemTesting.md
|
||||
|
||||
@@ -0,0 +1,190 @@
|
||||
Release Process - Create .deb packages
|
||||
======================================
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
The purpose of this process is to create and publish .deb packages for
|
||||
Zonemaster components, currently only Zonemaster-CLI, Zonemaster-Engine and
|
||||
Zonemaster-LDNS are covered.
|
||||
|
||||
The process to build the packages is split in two steps. In the first step "nightly
|
||||
packages" are updated. In the second step packages are promoted to "stable packages".
|
||||
|
||||
## 1. Update the nightly packages specification
|
||||
|
||||
Nightly packages are based on the develop branch of Zonemaster git repositories.
|
||||
The sources for nightly packages are kept in the branch `<distribution>-nightly`
|
||||
of the [Packages sources] repository. Where `<distribution>` corresponds to the
|
||||
name of the Debian or Ubuntu version the branch is building packages for.
|
||||
As Ubuntu packages are based on the Debian ones, this will most likely be a
|
||||
Debian version name.
|
||||
|
||||
For each package:
|
||||
|
||||
1. If dependencies have changed, update the `Build-Depends` and `Depends`
|
||||
section of the `debian/control` file for each required package to add
|
||||
and/or remove any dependencies that have changed.
|
||||
|
||||
2. If there are new files (such as executables), update `debian/*.manpages` and
|
||||
`debian/*.install` accordingly. This step is not required for new Perl
|
||||
modules, but will be for new scripts.
|
||||
|
||||
## 2. Promote the nightly build to stable
|
||||
|
||||
|
||||
When a new Zonemaster release of the relevant component has been
|
||||
[published on GitHub], and when the nightly package is working fine (the build
|
||||
is successful, it can be installed and is usable, all of that should have been
|
||||
already checked during the release testing if the package specification has not
|
||||
changed since), promote it to stable. The only difference between a nightly
|
||||
packages and its promoted version is the upstream tarball. While the nightly
|
||||
packages use the develop branch as upstream, the stable ones use a specific
|
||||
tag.
|
||||
|
||||
1. Locally merge the `<distribution>-nightly` branch into `<distribution>` of
|
||||
the [Packages sources] repository. The `.gitlab-ci.yml` and `pkg.sh` files
|
||||
should not be merged.
|
||||
For instance the following commands could be used to merge
|
||||
`bullseye-nightly` into `bullseye`:
|
||||
```
|
||||
git checkout bullseye
|
||||
git merge --no-commit bullseye-nightly
|
||||
git reset HEAD -- .gitlab-ci.yml */pkg.sh
|
||||
git checkout -- .gitlab-ci.yml */pkg.sh
|
||||
git commit
|
||||
```
|
||||
|
||||
2. Update the upstream ref in `pkg.sh` with the tag of the corresponding release
|
||||
for each package.
|
||||
|
||||
3. Update the `changelog` for each package, by adding a new entry. The first line
|
||||
should contain the package version in format
|
||||
`<project version>-<package version>`.
|
||||
|
||||
For example: `zonemaster-cli (3.1.0-3)` is the partial entry for
|
||||
Zonemaster-CLI version `3.1.0`, the package version is `3`. Package version
|
||||
is incremented when the package sources are updated but the upstream version
|
||||
(i.e. Zonemaster component version) remains the same.
|
||||
|
||||
4. Push the modifications to the packages sources repository. Then the packages
|
||||
are automatically built and deployed to package.zonemaster.net.
|
||||
|
||||
> Note: It is fairly important to perform all of those steps in "one push"
|
||||
> as the continuous deployment pipeline will start building the new packages
|
||||
> on the push event.
|
||||
|
||||
|
||||
## Test the packages
|
||||
|
||||
To test the newly created packages you can configure Zonemaster packages
|
||||
repository using:
|
||||
|
||||
```sh
|
||||
curl -LSsf https://package.zonemaster.net/setup.sh | sudo sh
|
||||
```
|
||||
|
||||
To configure the nightly repository use instead:
|
||||
|
||||
```sh
|
||||
curl -LSsf https://package.zonemaster.net/setup.sh | sudo nightly=yes sh
|
||||
```
|
||||
|
||||
The packages can then be installed using apt, e.g.:
|
||||
|
||||
```sh
|
||||
sudo apt install zonemaster-cli
|
||||
```
|
||||
|
||||
## Add support for a new OS version
|
||||
|
||||
Edit the `.gitlab-ci.yml` file to add three new jobs for the new OS version.
|
||||
The name of the job is in the format `{step}:{os}:{version codename}`, where
|
||||
step is one of `build`, `publish` and `test`. The jobs must extend a parent job
|
||||
named `.{step}`. The build and publish steps must also define the following
|
||||
variables:
|
||||
* `OS`: OS name as it is in the `/etc/os-release`;
|
||||
* `DISTRIBUTION`: Version codename as defined by `VERSION_CODENAME` in
|
||||
`/etc/os-release`, optionally suffixed by `-nightly`.
|
||||
|
||||
The container image used for building should be the same version as the targeted
|
||||
distribution.
|
||||
|
||||
Example for Ubuntu 22.04, codename "Jammy" the following is added to the CI
|
||||
file.
|
||||
```yml
|
||||
build:ubuntu:jammy:
|
||||
extends: .build
|
||||
image: ubuntu:jammy
|
||||
variables:
|
||||
# For nightly
|
||||
#DISTRIBUTION: jammy-nightly
|
||||
# For stable
|
||||
DISTRIBUTION: jammy
|
||||
OS: ubuntu
|
||||
|
||||
publish:ubuntu:jammy:
|
||||
extends: .publish
|
||||
image: ubuntu:jammy
|
||||
variables:
|
||||
# For nightly
|
||||
#DISTRIBUTION: jammy-nightly
|
||||
# For stable
|
||||
DISTRIBUTION: jammy
|
||||
OS: ubuntu
|
||||
needs:
|
||||
- build:ubuntu:jammy
|
||||
|
||||
test:ubuntu:jammy:
|
||||
extends: .test
|
||||
image: ubuntu:jammy
|
||||
# Only in nightly branches
|
||||
#variables:
|
||||
# nightly: 'yes'
|
||||
needs:
|
||||
- publish:ubuntu:jammy
|
||||
```
|
||||
|
||||
When publishing packages for a different Debian version, it may be prefered to
|
||||
create a separate set of branches. In this case the new CI jobs replace the olds
|
||||
ones in the CI file.
|
||||
|
||||
## Appendices
|
||||
|
||||
### Repositories location
|
||||
|
||||
* [Packages sources]: hold the sources for all Zonemaster packages.
|
||||
|
||||
Each package is split in two, one for the libraries and executable and an
|
||||
other one for the documentation. The documentation packages are marked as
|
||||
"Recommends" and will be installed by default alongside their corresponding
|
||||
package.
|
||||
|
||||
* [Common GitLab pipeline]: common ci/cd jobs for all branches in the packages
|
||||
source repository.
|
||||
|
||||
* [`package.zonemaster.net` content]: setup script and public verification key
|
||||
|
||||
### Publication pipeline overview
|
||||
|
||||
The continuous deployment pipeline performs 3 tasks:
|
||||
|
||||
1. `build`: build the packages using the `build.sh` script in the packages
|
||||
sources repository.
|
||||
|
||||
2. `publish`: update the [aptly] repository and publish the new packages.
|
||||
|
||||
3. `test`: perform a smoke test by installing the latest package and running the
|
||||
CLI.
|
||||
|
||||
### Further resources
|
||||
|
||||
* [Aptly documentation](https://www.aptly.info/doc/overview/)
|
||||
* [Debian maintainer guide](https://www.debian.org/doc/manuals/maint-guide/)
|
||||
* [Third party repository in Debian](https://wiki.debian.org/DebianRepository/UseThirdParty)
|
||||
|
||||
[aptly]: https://www.aptly.info
|
||||
[Packages sources]: https://gitlab.rd.nic.fr/zonemaster/packages/debian
|
||||
[Common GitLab pipeline]: https://gitlab.rd.nic.fr/zonemaster/ci/-/blob/main/deb-packaging.yml
|
||||
[`package.zonemaster.net` content]: https://gitlab.rd.nic.fr/zonemaster/packages/www/
|
||||
[published on GitHub]: ReleaseProcess-release.md#17-tag-the-release-with-git
|
||||
@@ -0,0 +1,107 @@
|
||||
Release process - Preparation
|
||||
=============================
|
||||
|
||||
|
||||
The steps in this document should be processed early in the release
|
||||
process, definitely before acceptance testing starts, but also before
|
||||
development has been completed.
|
||||
|
||||
|
||||
## 1. Update prerequisites
|
||||
|
||||
Make sure the [declaration of prerequisites] is up to date with regard to
|
||||
[SupportCriteria].
|
||||
|
||||
|
||||
## 2. Update [CI] configuration
|
||||
|
||||
Make sure the Travis configuration for each repo, in the `develop` branch
|
||||
is up to date with the [supported Perl versions].
|
||||
|
||||
* zonemaster-ldns - [.travis.yml][ldns.travis]
|
||||
* zonemaster-engine - [.github/workflows/ci.yml][engine.github-actions]
|
||||
* zonemaster-cli - [.travis.yml][cli.travis]
|
||||
* zonemaster-backend - [.travis.yml][backend.travis]
|
||||
|
||||
> Zonemaster-GUI uses no Perl and Zonemaster/Zonemaster uses no Travis.
|
||||
|
||||
|
||||
## 3. Verify that META.yml will have all the correct data
|
||||
|
||||
> This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster.
|
||||
|
||||
META.yml is created by Makefile.PL so if META.yml is not correct, then
|
||||
Makefile.PL must be updated.
|
||||
|
||||
1. Make a clean clone for each repository
|
||||
```
|
||||
git clean -dfx
|
||||
git reset --hard
|
||||
```
|
||||
2. Check out the `develop` branch. Check out the right commit
|
||||
of the submodule (LDNS) if Zonemaster-LDNS.
|
||||
```
|
||||
git checkout origin/develop
|
||||
git submodule update # Zonemaster-LDNS only
|
||||
```
|
||||
3. Run
|
||||
```
|
||||
perl Makefile.PL --no-ed25519 # zonemaster-ldns only
|
||||
perl Makefile.PL # other repositories
|
||||
```
|
||||
4. Verify that META.yml contains all the paths in the table in [Appendix META]
|
||||
below and that the value at each path matches the listed requirement.
|
||||
|
||||
|
||||
## 4. Verify that MANIFEST and MANIFEST.SKIP are up to date
|
||||
|
||||
> This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster.
|
||||
|
||||
MANIFEST must, directly or indirectly, list all files that should be installed.
|
||||
MANIFEST.SKIP must list all file that should not be installed, and what is
|
||||
counted are all files available when `make dist` is run.
|
||||
|
||||
|
||||
## 5. Check for deprecated features
|
||||
|
||||
Check all documentation in all repositories for deprecated features that are
|
||||
planned to be removed in the upcoming release.
|
||||
|
||||
If anything was found and there is no PR to remove it, then create an issue
|
||||
labelled `P-High` that something must be done before the release unless there is
|
||||
already an issue.
|
||||
|
||||
Removed feature will probably require that the major version is increased
|
||||
(breaking change). See "[Versions and Releases]".
|
||||
|
||||
|
||||
## Appendix META
|
||||
|
||||
Requirements for generated META.yml file.
|
||||
|
||||
Property | Requirement
|
||||
---------------------|----------------------------------------------------------------------
|
||||
abstract | component tag line
|
||||
author | current maintainer and original author
|
||||
license | [license string]
|
||||
name | name of the component
|
||||
recommends | all modules that aren't strictly required but still used if available
|
||||
requires | all required modules
|
||||
requires.perl | minimum perl version
|
||||
resources.bugtracker | link to the bug tracker
|
||||
resources.license | link to the license text
|
||||
resources.repository | link to the repository
|
||||
version | version number of the new release
|
||||
|
||||
|
||||
[CI]: https://github.com/travis-ci/travis-ci
|
||||
[declaration of prerequisites]: ../../public/installation/prerequisites.md
|
||||
[license string]: https://metacpan.org/pod/CPAN::Meta::Spec#license
|
||||
[SupportCriteria]: SupportCriteria.md
|
||||
[ldns.travis]: https://github.com/zonemaster/zonemaster-ldns/blob/develop/.travis.yml
|
||||
[engine.github-actions]: https://github.com/zonemaster/zonemaster-engine/blob/develop/.github/workflows/ci.yml
|
||||
[cli.travis]: https://github.com/zonemaster/zonemaster-cli/blob/develop/.travis.yml
|
||||
[backend.travis]: https://github.com/zonemaster/zonemaster-backend/blob/develop/.travis.yml
|
||||
[supported Perl versions]: ../../public/installation/prerequisites.md#supported-perl-versions
|
||||
[Appendix META]: #appendix-meta
|
||||
[Versions and Releases]: ../design/Versions%20and%20Releases.md
|
||||
530
zonemaster/docs/internal/maintenance/ReleaseProcess-release.md
Normal file
530
zonemaster/docs/internal/maintenance/ReleaseProcess-release.md
Normal file
@@ -0,0 +1,530 @@
|
||||
Release process - Release
|
||||
=========================
|
||||
|
||||
## Table of contents
|
||||
|
||||
* [1. Overview](#1-overview)
|
||||
* [2. Applicable components](#2-applicable-components)
|
||||
* [3. Updates to repositories](#3-updates-to-repositories)
|
||||
* [4. Determine the new version number](#4-determine-the-new-version-number)
|
||||
* [5. Update the Changes files]
|
||||
* [6. Set version number for Perl modules](#6-set-version-number-for-perl-modules)
|
||||
* [7. Set version number for GUI](#7-set-version-number-for-gui)
|
||||
* [8. Update Makefile.PL with required version](#8-update-makefilepl-with-required-version)
|
||||
* [9. Create a clean Git working area of *develop branch*](#9-create-a-clean-git-working-area-of-develop-branch)
|
||||
* [10. Produce distribution tarballs](#10-produce-distribution-tarballs)
|
||||
* [11. Produce distribution zip file](#11-produce-distribution-zip-file)
|
||||
* [12. Update Zonemaster repository main _README.md_](#12-update-zonemaster-repository-main-readmemd)
|
||||
* [13. Generate documents and check public documents](#13-generate-documents-and-check-public-documents)
|
||||
* [14. Upload to CPAN](#14-upload-to-cpan)
|
||||
* [15. Merge develop branch into master](#15-merge-develop-branch-into-master)
|
||||
* [16. Create Docker images and upload image to Docker Hub](#16-create-docker-images-and-upload-image-to-docker-hub)
|
||||
* [17. Tag the release with git](#17-tag-the-release-with-git)
|
||||
* [18. Announce the release](#18-announce-the-release)
|
||||
* [19. Merge master into develop](#19-merge-master-into-develop)
|
||||
* [20. Clean-up on discussion forum](#20-clean-up-on-discussion-forum)
|
||||
* [21. Clean-up on GitHub related to the release](#21-clean-up-on-github-related-to-the-release)
|
||||
* [Appendix A on version number in Makefile.PL](#appendix-a-on-version-number-in-makefilepl)
|
||||
* [Appendix B on reverting commits](#appendix-b-on-reverting-commits)
|
||||
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The steps in this document executes the actual release. They assume that
|
||||
development, the preparation steps and the QA testing have been concluded.
|
||||
To run the steps below a build system is needed. See
|
||||
[Build Environment Preparation] for how to set it up.
|
||||
|
||||
> **Note:** *Normally, the develop branch version of this document should be used.*
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 2. Applicable components
|
||||
|
||||
Every applicable step below should be run for each component. If there are no
|
||||
changes in a component (no release) it should be skipped. The main component
|
||||
(Zonemaster/Zonemaster) can never be skipped and should always be released.
|
||||
The components should be released in the following order:
|
||||
|
||||
* zonemaster-ldns
|
||||
* zonemaster-engine
|
||||
* zonemaster-cli
|
||||
* zonemaster-backend
|
||||
* zonemaster-gui
|
||||
* Zonemaster/Zonemaster
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 3. Updates to repositories
|
||||
|
||||
All updates to *develop branch* and *master branch* should go via pull
|
||||
requests following the usual process. That is just assumed here.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 4. Determine the new version number
|
||||
|
||||
The version number of the new release should be chosen according to
|
||||
[Versions and Releases] document.
|
||||
|
||||
Each component listed above should have its version number. The Zonemaster
|
||||
Product (Zonemaster/Zonemaster) version number also refer to the version
|
||||
of the other components.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 5. Update the Changes files
|
||||
|
||||
Any changes since the last release must be documented in the Changes files.
|
||||
Refer to any GitHub issues or pull requests related to the change by the
|
||||
issue number or pull request number or both.
|
||||
|
||||
The updates to the *Changes* file are done to the *develop branch*.
|
||||
|
||||
* zonemaster-ldns - [Changes LDNS]
|
||||
* zonemaster-engine - [Changes Engine]
|
||||
* zonemaster-cli - [Changes CLI]
|
||||
* zonemaster-backend - [Changes Backend]
|
||||
* zonemaster-gui - [Changes GUI]
|
||||
* Zonemaster/Zonemaster
|
||||
- First update [Changes Zonemaster]
|
||||
- Then update the [RELEASE.md] page (use content of *Changes* file, only
|
||||
latest release) to match the upcoming [Github release page].
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 6. Set version number for Perl modules
|
||||
|
||||
> This step does not apply to Zonemaster/Zonemaster and Zonemaster-GUI
|
||||
|
||||
The version numbers is to be set in these Perl modules in the *develop branch*:
|
||||
|
||||
* zonemaster-ldns - [LDNS.pm]
|
||||
* zonemaster-engine - [Engine.pm]
|
||||
* zonemaster-cli - [CLI.pm]
|
||||
* zonemaster-backend - [Backend.pm]
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 7. Set version number for GUI
|
||||
|
||||
> This step applies to Zonemaster-GUI only
|
||||
|
||||
Update the following files in the *develop branch* of **Zonemaster-GUI**:
|
||||
|
||||
* [package.json][package.json GUI]
|
||||
- In the top of the file, the version is given after "version".
|
||||
- The file `package-lock.json` is ignored
|
||||
|
||||
Update the following file in the *develop branch* of **Zonemaster/Zonemaster**:
|
||||
|
||||
* [public/installation/zonemaster-gui.md][Installation.md GUI]
|
||||
- The version is both part of the filename (zip file) and part of the download
|
||||
path (a directory). Both are repeated several times, once per OS.
|
||||
|
||||
> The update of the installation document can preferably be done in the same
|
||||
> pull request as the update of the `Changes` file for Zonemaster/Zonemaster
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 8. Update Makefile.PL with required version
|
||||
|
||||
> This section is relevant for Zonemaster-Engine, Zonemaster-CLI and
|
||||
> Zonemaster-Backend.
|
||||
|
||||
If needed, update Makefile.PL in the *develop branch*. See [Appendix A] for
|
||||
how the version number should be specified in `Makefile.PL`.
|
||||
|
||||
Usually let Zonemaster-Engine, Zonemaster-CLI and Zonemaster-Backend,
|
||||
respectively, require the version of other the Zonemaster components
|
||||
(see below) included in this release, because that is what has been tested.
|
||||
|
||||
If a component will not be updated by this release, then it can continue to
|
||||
require the previous version unless it must be change to resolve some issue,
|
||||
and then the version of the requiring component must also be updated.
|
||||
|
||||
In **[Zonemaster-Engine Makefile.PL]** set the lowest version of Zonemaster-LDNS
|
||||
that Zonemaster-Engine requires. E.g.
|
||||
|
||||
```
|
||||
requires 'Zonemaster::LDNS' => 2.001;
|
||||
```
|
||||
|
||||
In **[Zonemaster-CLI Makefile.PL]** and **[Zonemaster-Backend Makefile.PL]**,
|
||||
set the minimum required versions of Zonemaster-LDNS and Zonemaster-Engine.
|
||||
E.g.
|
||||
|
||||
```
|
||||
requires 'Zonemaster::Engine' => 4.000;
|
||||
requires 'Zonemaster::LDNS' => 2.001;
|
||||
```
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 9. Create a clean Git working area of *develop branch*
|
||||
|
||||
Make sure that you have checked out the `develop` branch and that your clone is
|
||||
up-to-date.
|
||||
```
|
||||
git fetch --all
|
||||
git branch
|
||||
```
|
||||
Empty the submodule area (LDNS). Zonemaster-LDNS only.
|
||||
```
|
||||
git submodule deinit -f ldns
|
||||
```
|
||||
Make sure your working directory is clean.
|
||||
```
|
||||
git status --ignored
|
||||
```
|
||||
Or clean it.
|
||||
```
|
||||
git clean -dfx
|
||||
git reset --hard
|
||||
```
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 10. Produce distribution tarballs
|
||||
|
||||
> This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster
|
||||
|
||||
See [Release process - Create Test Distribution], sections 4-6 for more details
|
||||
and what warnings that could be ignored.
|
||||
```
|
||||
perl Makefile.PL --no-ed25519 # For Zonemaster-LDNS:
|
||||
```
|
||||
```
|
||||
perl Makefile.PL # For other components
|
||||
```
|
||||
```
|
||||
make all # For all
|
||||
make distcheck
|
||||
make dist
|
||||
```
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 11. Produce distribution zip file
|
||||
|
||||
> This section is relevant for Zonemaster-GUI only.
|
||||
|
||||
For this you need a [build environment for Node.js], on which you create
|
||||
the zip file. See [Release process - Create Test Distribution], sections 7
|
||||
for more details
|
||||
|
||||
Build the distribution zip file:
|
||||
```
|
||||
npm install
|
||||
npm run build
|
||||
npm run release
|
||||
```
|
||||
|
||||
> If you get building errors, repeat the `nvm` commands in
|
||||
> [build environment for Node.js] first.
|
||||
>
|
||||
> You can ignore warnings and security fixes at this stage, and do not run
|
||||
> any `npm audit fix`.
|
||||
|
||||
The distribution zip file is in the root level of the zonemaster-gui folder.
|
||||
Its name is `zonemaster_web_gui_v0.0.0.zip` with correct version.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 12. Update Zonemaster repository main _README.md_
|
||||
|
||||
> This section is relevant for Zonemaster/Zonemaster only.
|
||||
|
||||
If needed, update the following section of the Zonemaster repository main
|
||||
[README.md][Zonemaster main README] file in *develop branch*:
|
||||
|
||||
* Notable bugs and issues
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 13. Generate documents and check public documents
|
||||
|
||||
> The two sub-sections here are relevant for Zonemaster/Zonemaster only.
|
||||
|
||||
### 13.1. Generate documents
|
||||
|
||||
If no files in neither Zonemaster/Zonemaster nor Zonemaster-Engine have been
|
||||
updated this section can be skipped.
|
||||
|
||||
1. On a computer install Zonemaster-LDNS and Zonemaster-Engine using the
|
||||
distribution packages created for this release.
|
||||
2. Clone Zonemaster/Zonemaster and check out the *develop branch*. The
|
||||
working area should be clean (`git status --ignore`).
|
||||
3. Go to the [utils][utils Zonemaster] directory and create the files as
|
||||
documented in the [README.pm][Zonemaster utils README] file in that
|
||||
directory.
|
||||
4. If any of the created files has been updated (`git status`) then it
|
||||
should be added to the *develop branch* via a pull request.
|
||||
5. No reviewer or approval is required for this change.
|
||||
|
||||
### 13.2 Check public documents
|
||||
|
||||
> The step above, 13.1, should be completed (merged to develop branch) before
|
||||
> this step is run to avoid double errors.
|
||||
|
||||
Prior to this step `mdbook-linkcheck` must be installed (see
|
||||
[Build environment preparation]). Run from the Zonemaster/Zonemaster
|
||||
repository (develop branch checked out):
|
||||
|
||||
```
|
||||
mdbook-linkcheck -s docs/public/
|
||||
```
|
||||
|
||||
1. If any error is reported, correct the file or files.
|
||||
2. Add changes to the *develop branch* via a pull request.
|
||||
3. No reviewer or approval is required for this change.
|
||||
4. Repeat the command after merging the changes to verify that the found errors
|
||||
have been resolved.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 14. Upload to CPAN
|
||||
|
||||
> This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster.
|
||||
|
||||
For each component that is to be updated in this release, publish the
|
||||
distribution tarball created following this document on CPAN.
|
||||
Currently we use the organizational account [ZNMSTR] on [PAUSE] for doing
|
||||
this.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 15. Merge develop branch into master
|
||||
|
||||
> For the steps in this section, it is assumed that the git "remote"
|
||||
> which is called "origin" points at "zonemaster/zonemaster.git",
|
||||
> "zonemaster/zonemaster-ldns.git" etc. This is default when making a
|
||||
> git clone. Use `git remote -v` to verify that.
|
||||
|
||||
Make sure you're up to date and your working directory is completely clean:
|
||||
|
||||
git fetch origin
|
||||
git status --ignored
|
||||
|
||||
> **Note:** To throw away any and all changes to tracked and untracked files you
|
||||
> can run `git clean -dfx ; git reset --hard`.
|
||||
|
||||
Verify if there are commits on `master` since last release:
|
||||
|
||||
TAG=$( git tag --list --sort=-creatordate | head -n 1 )
|
||||
# count the number of commits in master since last release and
|
||||
# if the count is not 0, look for commits belonging to master and develop
|
||||
[ $(git rev-list --count $TAG..master) -ne 0 ] && cat <( git rev-list $TAG^2..develop ) <( git rev-list $TAG..master ) | sort | uniq -d
|
||||
|
||||
If commits are returned by this previous command, some additional work is
|
||||
needed. See [Appendix B] for that.
|
||||
|
||||
Finally once `master` branch is ready, create a pull request from `develop`
|
||||
into `master` and merge it. No reviewer or approval is required for this
|
||||
update.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 16. Create Docker images and upload image to Docker Hub
|
||||
|
||||
1. Follow the instructions in [Create Docker Image] to build a Docker images.
|
||||
2. Upload the Zonemaster-CLI image to [Docker Hub] for Zonemaster using the
|
||||
instructions in [Create Docker Image].
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 17. Tag the release with git
|
||||
|
||||
For each repository, go to "releases" in GitHub and select "draft a new release".
|
||||
Use the version number as tag and create a new release description. Use the
|
||||
section of Changes file for the relevant release and make links of everything
|
||||
that can have meaningful links, especially make links to issues and PRs.
|
||||
|
||||
For Zonemaster-GUI, add the *distribution zip file* as attached file to the
|
||||
release description in GitHub.
|
||||
|
||||
Always release the Zonemaster Product (Zonemaster/Zonemaster) as the last step.
|
||||
|
||||
The releases pages:
|
||||
|
||||
* [Zonemaster-LDNS Releases]
|
||||
* [Zonemaster-Engine Releases]
|
||||
* [Zonemaster-CLI Releases]
|
||||
* [Zonemaster-Backend Releases]
|
||||
* [Zonemaster-GUI Releases]
|
||||
* [Zonemaster Product Releases] - use the [RELEASE.md] created in
|
||||
[step 5][5. Update the Changes files].
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 18. Announce the release
|
||||
|
||||
1. Send emails to the mailing lists `zonemaster-users` and `zonemaster-announce`
|
||||
(the same email content will usually work fine). Always refer to the
|
||||
[Github release page], but the URL with the version.
|
||||
2. Forward the `zonemaster-users` email to the mailing list `zonemaster-group`.
|
||||
3. Create an announcement on the [Zonemaster discussion forum] on GitHub.
|
||||
1. Choose "New discussion"
|
||||
2. Select "Announcements"
|
||||
3. Use Zonemaster version as title
|
||||
4. Use the body of the [Github release page] for the version as the body of
|
||||
the announcement.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 19. Merge master into develop
|
||||
|
||||
Create a pull request from `master` on github back into `develop` and merge
|
||||
it. No review or approval is required for this update.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 20. Clean-up on discussion forum
|
||||
|
||||
On the [Zonemaster discussion forum] on GitHub, close the announcement of the
|
||||
previous version. Also close discussions that are not relevant to keep open,
|
||||
i.e. resolved issues and other questions that have been answered and some time
|
||||
has passed with no further follow-up questions.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## 21. Clean-up on Github related to the release
|
||||
|
||||
For each repository:
|
||||
* Zonemaster/Zonemaster
|
||||
* zonemaster-ldns
|
||||
* zonemaster-engine
|
||||
* zonemaster-cli
|
||||
* zonemaster-backend
|
||||
* zonemaster-gui
|
||||
|
||||
Do the following steps related to the release:
|
||||
1. Check the issues with the release as milestone.
|
||||
1. Close if completed or irrelevant.
|
||||
2. Else move to a new milestone.
|
||||
2. Verify that the milestone of the release is 100% complete.
|
||||
1. Close if completed.
|
||||
2. Else make it complete and then close it.
|
||||
3. Verify that there are milestones for at least two of the next standard releases.
|
||||
1. If not, create the appropriate vYYYY.x milestones (e.g v2025.1)
|
||||
2. Also, if no due date has been chosen, set YYYY-06-15 for the .1 release and
|
||||
YYYY-12-15 for the .2 release.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
|
||||
|
||||
## Appendix A on version number in Makefile.PL
|
||||
|
||||
As described above, `Makefile.PL` of Zonemaster-CLI and Zonemaster-Backend,
|
||||
respectively, must be specified with the lowest supported version of
|
||||
Zonemaster::LDNS and Zonemaster::Engine, respectively. Zonemaster-Engine
|
||||
must have that of Zonemaster::LDNS.
|
||||
|
||||
The versions of Zonemaster::LDNS and Zonemaster::Engine are defined in the
|
||||
format `vX.Y.Z` and it is important how this is written in `Makefile.PL`.
|
||||
|
||||
For lowest risk of error follow the following steps:
|
||||
|
||||
1. Expand the version number with leading zeros on second ("Y") and third
|
||||
("Z") level. Remove the leading `v` and the second and third dots.
|
||||
E.g. `v2.1.2` = `2.001002`.
|
||||
2. Decide if the third level can be skipped, e.g. `v2.1.2` > `2.001`.
|
||||
3. Please note that if the version in `Makefile.PL` is set to `2.1` then
|
||||
the interpretation is that the "v" version is `v2.100.0` or greater.
|
||||
|
||||
When specifying the version of Zonemaster::LDNS and Zonemaster::Engine in
|
||||
`Makefile.PL` always use the expanded format, e.g. `2.001002` or `2.001`
|
||||
depending on the need.
|
||||
|
||||
For other libraries, other formats may be correct. If the version of the
|
||||
library only has two levels ("X.Y") then other rules apply. Also note
|
||||
that the version in Zonemaster::Backend is specified as `X.Y.Z` without
|
||||
the "v", which may affect the version comparison.
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
## Appendix B on reverting commits
|
||||
|
||||
When merging `develop` into `master` a merge conflict could occur. This is due
|
||||
to the fact that some commits belongs to both branches. Usually this is the
|
||||
result of a merge request in `master` branch instead of `develop` during
|
||||
development. Once this happens, the faulty merge is reverted on `master` and
|
||||
merged into `develop`. Depending on the steps chosen, this could lead to having
|
||||
the same commit in both branches.
|
||||
|
||||
To avoid merge conflict, it is necessary to revert the revert commits on
|
||||
`master` (yes revert of the revert) before merging `develop` into `master`.
|
||||
|
||||
### How would the release officer find the commit to revert?
|
||||
|
||||
Usually a revert commit contains a predefined subject (or title) looking like:
|
||||
`Revert "subject of the reverted commit"`.
|
||||
|
||||
One can looks for commits with this string using a command like:
|
||||
|
||||
TAG=$( git tag --list --sort=-creatordate | head -n 1 )
|
||||
for c in $(cat <( git rev-list $TAG^2..develop ) <( git rev-list $TAG..master ) | sort | uniq -d); \
|
||||
do git log --oneline --grep="Revert \"$(git show -s --pretty=%s $c)\"" $c~..master ^$TAG ; \
|
||||
done
|
||||
|
||||
Or look for them visually with:
|
||||
|
||||
git log --oneline --graph $TAG..master
|
||||
|
||||
Once found, either revert each commits (`git revert <commit> ...`) or the merge
|
||||
commit.
|
||||
|
||||
### How would the release officer know the parent number to revert?
|
||||
|
||||
In case one reverts the merge commit, since it was merged into master, the
|
||||
parent number is `1`.
|
||||
|
||||
git revert -m 1 <merge commit>
|
||||
|
||||
|
||||
[(Top)](#table-of-contents)
|
||||
|
||||
<!-- Zonemaster links point on purpose on the develop branch. -->
|
||||
[5. Update the Changes files]: #5-update-the-changes-files
|
||||
[Appendix A]: #appendix-a-on-version-number-in-makefilepl
|
||||
[Appendix B]: #appendix-b-on-reverting-commits
|
||||
[Backend.pm]: https://github.com/zonemaster/zonemaster-backend/blob/develop/lib/Zonemaster/Backend.pm
|
||||
[Build environment preparation]: ../distrib-testing/README.md
|
||||
[Build environment for Node.js]: ../distrib-testing/Ubuntu-Node.js-build-environment.md
|
||||
[CI]: https://github.com/travis-ci/travis-ci
|
||||
[CLI.pm]: https://github.com/zonemaster/zonemaster-cli/blob/develop/lib/Zonemaster/CLI.pm
|
||||
[CPAN]: https://www.cpan.org/
|
||||
[Changes Backend]: https://github.com/zonemaster/zonemaster-backend/blob/develop/Changes
|
||||
[Changes CLI]: https://github.com/zonemaster/zonemaster-cli/blob/develop/Changes
|
||||
[Changes Engine]: https://github.com/zonemaster/zonemaster-engine/blob/develop/Changes
|
||||
[Changes GUI]: https://github.com/zonemaster/zonemaster-gui/blob/develop/Changes
|
||||
[Changes LDNS]: https://github.com/zonemaster/zonemaster-ldns/blob/develop/Changes
|
||||
[Changes Zonemaster]: https://github.com/zonemaster/zonemaster-gui/blob/develop/Changes
|
||||
[Create Docker Image]: ReleaseProcess-create-docker-image.md
|
||||
[Docker Hub]: https://hub.docker.com/u/zonemaster
|
||||
[Engine.pm]: https://github.com/zonemaster/zonemaster-engine/blob/develop/lib/Zonemaster/Engine.pm
|
||||
[Github release page]: https://github.com/zonemaster/zonemaster/releases/latest
|
||||
[Installation.md GUI]: ../../public/installation/zonemaster-gui.md
|
||||
[LDNS.pm]: https://github.com/zonemaster/zonemaster-ldns/blob/develop/lib/Zonemaster/LDNS.pm
|
||||
[PAUSE]: https://pause.perl.org/pause/query
|
||||
[Package.json GUI]: https://github.com/zonemaster/zonemaster-gui/blob/develop/package.json
|
||||
[RELEASE.md]: ../../public/RELEASE.md
|
||||
[Release process - Create Test Distribution]: ReleaseProcess-create-test-distribution.md
|
||||
[Utils Zonemaster]: ../../../utils/
|
||||
[Version.ts GUI]: https://github.com/zonemaster/zonemaster-gui/blob/develop/src/environments/version.ts
|
||||
[Versions and releases]: ../design/Versions%20and%20Releases.md
|
||||
[ZNMSTR]: https://metacpan.org/author/ZNMSTR
|
||||
[Zonemaster Product Releases]: https://github.com/zonemaster/zonemaster/releases
|
||||
[Zonemaster main README]: ../../../README.md
|
||||
[Zonemaster utils README]: ../../../utils/README.md
|
||||
[Zonemaster-Backend Makefile.PL]: https://github.com/zonemaster/zonemaster-backend/blob/develop/Makefile.PL
|
||||
[Zonemaster-Backend Releases]: https://github.com/zonemaster/zonemaster-backend/releases
|
||||
[Zonemaster-CLI Makefile.PL]: https://github.com/zonemaster/zonemaster-cli/blob/develop/Makefile.PL
|
||||
[Zonemaster-CLI Releases]: https://github.com/zonemaster/zonemaster-cli/releases
|
||||
[Zonemaster discussion forum]: https://github.com/orgs/zonemaster/discussions
|
||||
[Zonemaster-Engine Makefile.PL]: https://github.com/zonemaster/zonemaster-engine/blob/develop/Makefile.PL
|
||||
[Zonemaster-Engine Releases]: https://github.com/zonemaster/zonemaster-engine/releases
|
||||
[Zonemaster-GUI Releases]: https://github.com/zonemaster/zonemaster-gui/releases
|
||||
[Zonemaster-LDNS Releases]: https://github.com/zonemaster/zonemaster-ldns/releases
|
||||
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
Release process - Test Planning
|
||||
===============================
|
||||
|
||||
The purpose of test planning is to raise the quality by making the release
|
||||
testing more structured, getting better coverage and finding more bugs.
|
||||
This gives us greater faith in our releases.
|
||||
|
||||
## Release testing start up-meeting
|
||||
|
||||
1. Compile a list of all pull requests that should be tested.
|
||||
|
||||
2. For each test item, discuss how it could and should be tested.
|
||||
Make sure there is a heading titled "How to test this PR" in the pull request
|
||||
description.
|
||||
Add it if needed.
|
||||
Add/update notes under this heading to reflect the conclusions made.
|
||||
|
||||
3. Discuss prioritization of the test items and who should test what.
|
||||
Note down all the conclusions.
|
||||
36
zonemaster/docs/internal/maintenance/ReleaseProcess.md
Normal file
36
zonemaster/docs/internal/maintenance/ReleaseProcess.md
Normal file
@@ -0,0 +1,36 @@
|
||||
Release process
|
||||
===============
|
||||
|
||||
This process has been split into different parts which are described in their
|
||||
own documents.
|
||||
|
||||
## 1. [Preparation]
|
||||
|
||||
The steps in this subprocess should be processed early in the release
|
||||
process, definitely before acceptance testing starts, but also before
|
||||
development has been completed.
|
||||
|
||||
|
||||
## 2. [Test planning]
|
||||
|
||||
This phase should be performed after the end of development but before
|
||||
acceptance testing starts.
|
||||
|
||||
|
||||
## 3. [Create test distributions]
|
||||
|
||||
The purpose of this part is to create the test distributions that can be
|
||||
used in QA testing for a release. It can also be used to create test
|
||||
distributions to verify a pull request.
|
||||
|
||||
|
||||
## 4. [Release]
|
||||
|
||||
The steps in this part executes the actual release. They assume that
|
||||
development, the preparation steps and the QA testing have been concluded.
|
||||
|
||||
|
||||
[Create test distributions]: ReleaseProcess-create-test-distribution.md
|
||||
[Preparation]: ReleaseProcess-preparation.md
|
||||
[Release]: ReleaseProcess-release.md
|
||||
[Test planning]: ReleaseProcess-test-planning.md
|
||||
29
zonemaster/docs/internal/maintenance/StyleGuide.md
Normal file
29
zonemaster/docs/internal/maintenance/StyleGuide.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# Style Guide
|
||||
|
||||
## Scope
|
||||
|
||||
The following style guide applies to document text and certain file names
|
||||
specified below.
|
||||
|
||||
## Guidelines
|
||||
|
||||
* Zonemaster is always written as **Zonemaster**, never shortened (e.g. "ZM") or
|
||||
uncapitalized (e.g. "zonemaster").
|
||||
* Case-insensitive regexes are always written out with the ignore-case flag
|
||||
(e.g. `/[a-z]/i`).
|
||||
* For variable names in test case specifications each word is capitalized (e.g.
|
||||
"Domain Part"). If a word is an abbreviation, it is usually written with all
|
||||
capitals, e.g. "DNS".
|
||||
* When writing Markdown documents, use lower case fragments when referring to
|
||||
internal headings' anchors, i.e. use `#objective` not `#Objective` to create
|
||||
a link to the "Objective" section.
|
||||
* When linking to other documents and including the URL in the rendered text,
|
||||
put angle brackets around the URL, i.e. use the [CommonMark autolink] syntax.
|
||||
I.e. write as `<https://example.com/>` not just as `https://example.com/`.
|
||||
|
||||
If the angle brackets are not included the URL is still rendered as a link on
|
||||
GitHub (per [GFM autolink] syntax), but other tools may not recognize it as a
|
||||
link.
|
||||
|
||||
[CommonMark autolink]: https://spec.commonmark.org/0.30/#autolinks
|
||||
[GFM autolink]: https://github.github.com/gfm/#autolinks-extension-
|
||||
156
zonemaster/docs/internal/maintenance/SupportCriteria.md
Normal file
156
zonemaster/docs/internal/maintenance/SupportCriteria.md
Normal file
@@ -0,0 +1,156 @@
|
||||
Support criteria
|
||||
================
|
||||
|
||||
This document hosts a set of guiding principles for selecting configuration
|
||||
parameter items to support.
|
||||
|
||||
|
||||
## General
|
||||
|
||||
It is legitimate to avoid supporting items that are otherwise perfectly eligible
|
||||
for support, just for the sake of limiting the total number of configuration
|
||||
tuples.
|
||||
|
||||
|
||||
## Architectures
|
||||
|
||||
Zonemaster is actively tested on the amd64/x86_64 processor architecture. No
|
||||
testing is currently done on ARM architecture.
|
||||
|
||||
|
||||
## Operating systems
|
||||
|
||||
Zonemaster is actively tested on the following operating systems:
|
||||
|
||||
* Debian
|
||||
* FreeBSD
|
||||
* Rocky Linux
|
||||
* Ubuntu
|
||||
|
||||
CentOS is no longer supported and has been replaced by Rocky Linux.
|
||||
|
||||
## Operating system versions
|
||||
|
||||
### List of versions is set
|
||||
|
||||
The criteria below are used at the time of release of Zonemaster to determine what versions
|
||||
that are supported for the version of Zonemaster to be released. That list of versions is
|
||||
fixed for the lifetime of the Zonemaster version.
|
||||
|
||||
### Criteria
|
||||
|
||||
The following criteria are used to determine which version of the operating
|
||||
system that is supported:
|
||||
* Minor version/point release/patch level should not be specified.
|
||||
* Operating system versions without long term support form their
|
||||
vendor should not be supported.
|
||||
* Operating system versions that have reached their end-of-life (or end of
|
||||
general support) should not be supported.
|
||||
* Operating system versions that are expected to reach their end-of-life (or
|
||||
end of general support) within the lifetime of the Zonemaster version should
|
||||
not be supported.
|
||||
* Operating system versions that do not provide the prerequisites for
|
||||
Zonemaster should not be supported.
|
||||
|
||||
### Operating system specific guidelines
|
||||
|
||||
* Debian:
|
||||
* Only the current "stable" release is supported.
|
||||
* Current "stable" is listed on
|
||||
<https://wiki.debian.org/DebianReleases#Current_Releases.2FRepositories>.
|
||||
|
||||
* FreeBSD:
|
||||
* One major branch is supported. The selected major branch is supported for
|
||||
its lifetime, and then replaced by the newest major branch. The replacement
|
||||
is done when EOL will be reached within the expected lifetime of the
|
||||
Zonemaster release.
|
||||
* For the selected major release, only the newest point release is tested.
|
||||
* The active major branches are found on <https://www.freebsd.org/security/>
|
||||
(scroll down to "Supported FreeBSD releases").
|
||||
|
||||
* Rocky Linux:
|
||||
* All major versions that have not reached EOL are supported.
|
||||
* If the EOL of a major version is within the expected lifetime of the
|
||||
Zonemaster release then that major version is not supported.
|
||||
* Only the newest point release is tested.
|
||||
* Active releases are listed on <https://rockylinux.org/download> and
|
||||
<https://en.wikipedia.org/wiki/Rocky_Linux#Releases>.
|
||||
|
||||
* Ubuntu:
|
||||
* All LTS versions that have not reached the "End of Standard Support" are
|
||||
supported.
|
||||
* If the "End of Standard Support" for an LTS version is within the expected
|
||||
lifetime of the Zonemaster release then that LTS version is not supported.
|
||||
* For each LTS version, only the newest point release is tested.
|
||||
* LTS releases are listed on <https://wiki.ubuntu.com/Releases>.
|
||||
|
||||
|
||||
## Database engines
|
||||
|
||||
Zonemaster provides database integrations for these database engines:
|
||||
|
||||
* MariaDB (MySQL)
|
||||
* PostgreSQL
|
||||
* SQLite (included in Zonemaster-Backend dependency)
|
||||
|
||||
|
||||
## Database engine versions
|
||||
|
||||
The database engine versions that are provided by the respective supported
|
||||
operating system version should be supported.
|
||||
|
||||
Database engine versions that lack required features cannot be supported.
|
||||
|
||||
* Database engine versions provided by each version of Debian are listed here:
|
||||
* <https://packages.debian.org/search?searchon=names&keywords=mariadb-server>
|
||||
* <https://packages.debian.org/search?searchon=names&keywords=postgresql>
|
||||
|
||||
* Database engine versions provided FreeBSD are listed here:
|
||||
* <https://ports.freebsd.org/cgi/ports.cgi?query=mysql&stype=name&sektion=databases>
|
||||
and look for "mysql??-server-*" (FreeBSD does not support MariaDB in a
|
||||
default Backend installation).
|
||||
* <https://ports.freebsd.org/cgi/ports.cgi?stype=name&sektion=databases&query=postgresql>
|
||||
|
||||
* Database engine versions provided by each version of Rocky Linux are listed here: TBP
|
||||
|
||||
* Database engine versions provided by each version of Ubuntu are listed here:
|
||||
* <https://packages.ubuntu.com/search?suite=default§ion=all&arch=any&searchon=names&keywords=mariadb-server>
|
||||
* <https://packages.ubuntu.com/search?suite=default§ion=all&arch=any&searchon=names&keywords=postgresql>
|
||||
|
||||
|
||||
## Translation locales
|
||||
|
||||
Can we say something about how the current triple of locales was chosen? How
|
||||
about including new languages?
|
||||
|
||||
|
||||
## System locales
|
||||
|
||||
A base line locale should be included.
|
||||
|
||||
Locales that expose classes of bugs should be included.
|
||||
|
||||
|
||||
## Perl versions
|
||||
|
||||
The Perl versions that are provided by the respective supported operating system
|
||||
version should be supported.
|
||||
|
||||
The point release should not be specified.
|
||||
|
||||
* Perl versions provided by each version of Debian are listed here:
|
||||
* <https://packages.debian.org/search?searchon=names&keywords=perl>
|
||||
|
||||
* Perl versions provided FreeBSD are listed here:
|
||||
* <https://ports.freebsd.org/cgi/ports.cgi?stype=name&sektion=lang&query=perl>
|
||||
|
||||
* Perl versions provided by each version of Rocky Linux are listed here: TBP
|
||||
|
||||
* Perl versions provided by each version of Ubuntu are listed here:
|
||||
* <https://packages.ubuntu.com/search?suite=default§ion=all&arch=any&searchon=names&keywords=perl>
|
||||
|
||||
|
||||
## Nice-to-have resources
|
||||
|
||||
* [Debian point releases](https://wiki.debian.org/DebianReleases/PointReleases)
|
||||
* [Ubuntu patch levels](https://wiki.ubuntu.com/Releases)
|
||||
197
zonemaster/docs/internal/maintenance/SystemTesting.md
Normal file
197
zonemaster/docs/internal/maintenance/SystemTesting.md
Normal file
@@ -0,0 +1,197 @@
|
||||
System testing
|
||||
==============
|
||||
Before a new version of Zonemaster can be released it must pass three levels of
|
||||
system testing: Installation Testing, Smoke Testing and Acceptance Testing.
|
||||
Each test level is described in a separate section below. A separate section is
|
||||
reserved for the concept of Configurations, which is used by other sections.
|
||||
|
||||
|
||||
## 1. Configurations
|
||||
|
||||
The purpose of configurations is to provide different contexts for the tests to
|
||||
run in.
|
||||
|
||||
A configuration is a tuple of the following parameters:
|
||||
|
||||
* architecture (e.g. x86_64)
|
||||
* operating system version (e.g. Ubuntu 14.04)
|
||||
* database engine version (e.g. PostgreSQL 9.3)
|
||||
* system locale (e.g. en_US.UTF-8)
|
||||
* Perl version (e.g. 5.20)
|
||||
|
||||
The set of possible values for the following configuration parameters (except
|
||||
for system locale) are declared in the README.md of the top-level zonemaster
|
||||
repository.
|
||||
|
||||
The set of possible values for the system locale configuration parameter is:
|
||||
|
||||
* C
|
||||
* en_US.UTF-8
|
||||
|
||||
Regarding minimum hardware requirements, the following defaults should be chosen:
|
||||
|
||||
* CPU: 2 cores
|
||||
* RAM: 2GB
|
||||
* Storage: 20GB
|
||||
|
||||
## 2. Installation testing
|
||||
|
||||
This test level validates that all components of Zonemaster can be installed
|
||||
according to their respective installation instructions.
|
||||
|
||||
|
||||
### Configurations
|
||||
|
||||
The set of configurations must include at least:
|
||||
* One configuration for each supported architecture.
|
||||
* One configuration for each supported operating system version.
|
||||
* One configuration for each supported database engine version.
|
||||
|
||||
|
||||
### Procedure
|
||||
|
||||
1. Make sure you have the correct preliminary distribution tarball for each
|
||||
component. See [Create Test Distribution].
|
||||
|
||||
2. For each configuration:
|
||||
|
||||
1. Prepare a machine
|
||||
1. Allocate a machine with the architecture specified by the configuration.
|
||||
2. Follow the preparation document for the operating system specified by the configuration.
|
||||
* [Debian-Preparation]
|
||||
* [FreeBSD-Preparation]
|
||||
* [Ubuntu-Preparation]
|
||||
* Rocky-Linux-Preparation (TBD)
|
||||
|
||||
2. Install Zonemaster LDNS
|
||||
1. Install dependencies according to the [LDNS installation] instructions.
|
||||
2. Install the preliminary distribution tarball for zonemaster-ldns.
|
||||
|
||||
```sh
|
||||
sudo cpanm Zonemaster-LDNS-${LDNS_VERSION}.tar.gz
|
||||
```
|
||||
|
||||
3. Follow the [post-installation sanity check][LDNS sanity check] section of the installation guide to the letter.
|
||||
|
||||
3. Install Zonemaster Engine
|
||||
1. Install dependencies according to the [Engine installation] instructions.
|
||||
2. Install the preliminary distribution tarball for zonemaster-engine.
|
||||
|
||||
```sh
|
||||
sudo cpanm Zonemaster-Engine-${ENGINE_VERSION}.tar.gz
|
||||
```
|
||||
|
||||
3. Follow the [post-installation sanity check][Engine sanity check] section of the installation guide to the letter.
|
||||
|
||||
4. Install Zonemaster Backend
|
||||
1. Install dependencies according to the [Backend installation] instructions.
|
||||
2. Install the preliminary distribution tarball for zonemaster-backend.
|
||||
|
||||
```sh
|
||||
sudo cpanm Zonemaster-Backend-${BACKEND_VERSION}.tar.gz
|
||||
```
|
||||
|
||||
3. Follow the configuration section of the [Backend installation] instructions to the letter.
|
||||
4. Follow the startup section of the [Backend installation] instructions to the letter.
|
||||
5. Follow the [smoke test] section of the installation guide to the letter.
|
||||
|
||||
5. Install Zonemaster GUI
|
||||
1. Follow the prerequisites section of the [GUI installation] instructions to the letter.
|
||||
2. Follow the installation section of the [GUI installation] instructions to the letter.
|
||||
3. Follow the configuration section of the [GUI installation] instructions to the letter.
|
||||
4. Follow the startup section of the [GUI installation] instructions to the letter.
|
||||
5. Follow the [post-installation sanity check][GUI sanity check] section of the installation guide to the letter.
|
||||
|
||||
6. Install Zonemaster CLI
|
||||
1. Follow the prerequisites section of the [CLI installation] installation to the letter.
|
||||
2. Install the preliminary distribution tarball for zonemaster-backend.
|
||||
|
||||
```sh
|
||||
sudo cpanm Zonemaster-CLI-${CLI_VERSION}.tar.gz
|
||||
```
|
||||
|
||||
3. Follow the [post-installation sanity check][CLI sanity check] section of the installation guide to the letter.
|
||||
|
||||
|
||||
## 3. Smoke testing
|
||||
|
||||
This test level validates that fundamental use cases:
|
||||
|
||||
* work independent of specific configurations
|
||||
* weren't broken by new changes
|
||||
|
||||
|
||||
### Configurations
|
||||
|
||||
... To be specified.
|
||||
|
||||
|
||||
### Procedure
|
||||
|
||||
For each configuration:
|
||||
|
||||
1. Prepare an installation
|
||||
|
||||
2. Smoke test of Zonemaster CLI
|
||||
|
||||
1. Test a working domain (e.g. `afnic.fr`)
|
||||
2. Test working IDN (e.g. `президент.рф`)
|
||||
3. Test a broken domain (e.g. `error.com`)
|
||||
4. Working domains not signed with DNSSEC (e.g. `google.com`)
|
||||
5. Working domains signed with DNSSEC (e.g. `iis.se`)
|
||||
6. Broken DNSSEC domains (e.g. `broken.dnssec.ee`)
|
||||
|
||||
3. Smoke test of Zonemaster GUI
|
||||
|
||||
1. Test progress bar
|
||||
2. Test presentation of results
|
||||
3. Test export
|
||||
4. Test history
|
||||
|
||||
|
||||
## 4. Acceptance testing
|
||||
|
||||
This test level validates that each change since last release:
|
||||
|
||||
* works independent of specific configurations
|
||||
* weren't broken by other new changes
|
||||
|
||||
|
||||
### Configurations
|
||||
|
||||
... To be specified.
|
||||
|
||||
|
||||
### Procedure
|
||||
|
||||
1. Prepare an installation
|
||||
|
||||
2. Acceptance testing through Zonemaster CLI
|
||||
|
||||
Test each new entry in the Changes files of *Zonemaster CLI* and *Zonemaster Engine*.
|
||||
|
||||
4. Acceptance testing through Zonemaster Backend
|
||||
|
||||
Test each new entry in the Changes file of *Zonemaster Backend*.
|
||||
|
||||
4. Acceptance testing through Zonemaster GUI
|
||||
|
||||
Test each new entry in the Changes file of *Zonemaster GUI*.
|
||||
|
||||
|
||||
|
||||
[Backend installation]: ../../public/installation/zonemaster-backend.md
|
||||
[CLI installation]: ../../public/installation/zonemaster-cli.md
|
||||
[CLI sanity check]: ../../public/installation/zonemaster-cli.md#post-installation-sanity-check
|
||||
[Create Test Distribution]: ../maintenance/ReleaseProcess-create-test-distribution.md
|
||||
[Debian-Preparation]: ../distrib-testing/Debian-build-environment.md
|
||||
[Engine installation]: ../../public/installation/zonemaster-engine.md
|
||||
[Engine sanity check]: ../../public/installation/zonemaster-engine.md#post-installation-sanity-check
|
||||
[FreeBSD-Preparation]: ../distrib-testing/FreeBSD-build-environment.md
|
||||
[GUI installation]: ../../public/installation/zonemaster-gui.md
|
||||
[GUI sanity check]: ../../public/installation/zonemaster-gui.md#post-installation-sanity-check
|
||||
[LDNS installation]: ../../public/installation/zonemaster-ldns.md#recommended-installation
|
||||
[LDNS sanity check]: ../../public/installation/zonemaster-ldns.md#post-installation-sanity-check
|
||||
[Requirements for IDN support]: https://github.com/zonemaster/zonemaster-ldns/blob/master/README.md#idn
|
||||
[Smoke test]: ../../public/installation/zonemaster-backend.md#61-smoke-test
|
||||
[Ubuntu-Preparation]: ../distrib-testing/Ubuntu-build-environment.md
|
||||
Reference in New Issue
Block a user