lucene/dev-tools/scripts/releaseWizard.yaml

1594 lines
68 KiB
YAML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# =====================================================================
# This file contains the definition TO-DO steps and commands to run for the
# releaseWizard.py script. It also contains Jinja2 templates for use in those
# definitions. See documentation for "groups" below the templates.
# Edit this file with an editor with YAML support, such as Sublime Text
# for syntax highlighting and context sensitive tag suggestion
# =====================================================================
#
# Templates may be included in any text by starting a line with this syntax:
# (( template=my_template_name ))
# Templates may contain other templates for easy re-use of snippets
# And of course all Jinja2 syntax for inclusion of variables etc is supported.
# See http://jinja.pocoo.org/docs/2.10/templates/ for details
# To add new global variables or functions/filters, edit releaseWizard.py
#
templates:
help: |
Welcome to the role as Release Manager for Lucene, and the releaseWizard!
The Release Wizard aims to walk you through the whole release process step by step,
helping you to to run the right commands in the right order, generating
e-mail templates for you with the correct texts, versions, paths etc, obeying
the voting rules and much more. It also serves as a documentation of all the
steps, with timestamps, preserving log files from each command etc.
As you complete each step the tool will ask you if the task is complete, making
it easy for you to know what is done and what is left to do. If you need to
re-spin a Release Candidate (RC) the Wizard will also help.
The Lucene project has automated much of the release process with various scripts,
and this wizard is the glue that binds it all together.
In the first TODO step in the checklist you will be asked to read up on the
Apache release policy and other relevant documents before you start the release.
NOTE: Even if we have great tooling and some degree of automation, there are
still many manual steps and it is also important that the RM validates
and QAs the process, validating that the right commands are run, and that
the output from scripts are correct before proceeding.
vote_logic: |
{% set passed = plus_binding >= 3 and minus < plus_binding %}
{% set too_few = plus_binding < 3 %}
{% set veto = plus_binding < minus %}
{% set reason = 'too few binding votes' if too_few else 'too many negative votes' if veto else 'unknown' %}
vote_macro: |
{% macro end_vote_result(plus_binding, plus_other, zero, minus) -%}
(( template=vote_logic ))
.Mail template {% if passed %}successful{% else %}failed{% endif %} vote
----
To: dev@lucene.apache.org
Subject: [{% if passed %}RESULT{% else %}FAILED{% endif %}] [VOTE] Release Lucene {{ release_version }} RC{{ rc_number }}
It's been >72h since the vote was initiated and the result is:
+1 {{ plus_binding + plus_other }} ({{ plus_binding }} binding)
0 {{ zero }}
-1 {{ minus }}
{% if not passed %}
Reason for fail is {{ reason }}.
{% endif %}
This vote has {% if passed %}PASSED{% else %}FAILED{% endif %}
----
{%- endmacro %}
announce_lucene: |
Title: Apache Lucene™ {{ release_version }} available
category: core/news
URL:
save_as:
The Lucene PMC is pleased to announce the release of Apache Lucene {{ release_version }}.
Apache Lucene is a high-performance, full-featured search engine library written entirely in Java. It is a technology suitable for nearly any application that requires structured search, full-text search, faceting, nearest-neighbor search across high-dimensionality vectors, spell correction or query suggestions.
This release contains numerous bug fixes, optimizations, and improvements, some of which are highlighted below. The release is available for immediate download at:
<https://lucene.apache.org/core/downloads.html>
### Lucene {{ release_version }} Release Highlights:
* Feature 1 pasted from WIKI release notes
* Feature 2 ...
Please read CHANGES.txt for a full list of {% if is_feature_release %}new features and {% endif %}changes:
<https://lucene.apache.org/core/{{ release_version_underscore }}/changes/Changes.html>
announce_lucene_mail: |
The template below can be used to announce the Lucene release to the
internal mailing lists.
.Mail template
----
To: dev@lucene.apache.org, java-user@lucene.apache.org
Subject: [ANNOUNCE] Apache Lucene {{ release_version }} released
(( template=announce_lucene_mail_body ))
----
announce_lucene_sign_mail: |
The template below can be used to announce the Lucene release to the
`announce@apache.org` mailing list. The mail *should be signed with PGP.*
and sent *from your `@apache.org` account*.
.Mail template
----
From: {{ gpg.apache_id }}@apache.org
To: announce@apache.org
Subject: [ANNOUNCE] Apache Lucene {{ release_version }} released
(( template=announce_lucene_mail_body ))
----
announce_lucene_mail_body: |
{% for line in load_lines(lucene_news_file, 5) -%}
{{ line }}
{%- endfor %}
# TODOs belong to groups for easy navigation in menus. Todo objects may contain asciidoc
# descriptions, a number of commands to execute, some links to display, user input to gather
# etc. Here is the documentation of each type of object. For further details, please consult
# the corresponding Python object in releaseWizard.py, as these are parsed 1:1 from yaml.
#
# - !TodoGroup
# id: unique_id
# title: Title which will appear in menu
# description: Longer description that will appear in sub-menu
# depends: ['group1_id', 'group2_id'] # Explicit dependencies for groups
# is_in_rc_loop: Tells that a group is thrown away on RC re-psin (default=False)
# todos: # Array of !Todo objects beloning to the group
# !Todo
# id: todo_id
# title: Short title that will appear in menu and elsewhere
# description: |
# The main description being printed when selecing the todo item. Here
# you should introduce the task in more detail. You can use {{ jinja_var }} to
# reference variables. See `releaseWizard.py` for list of global vars supported.
# You can reference state saved from earlier TODO items using syntax
# {{ todo_id.var_name }}
# with `var_name` being either fetched from user_input or persist_vars
# depends: # One or more dependencies which will bar execution
# - todo_id1
# - todo_id2
# vars: # Dictionary of jinja2 variables local to this TODO, e.g.
# logfile_path: "{{ [rc_folder, 'logs'] | path_join }}"
# # Vars can contain global jinja vars or local vars earlier defined (ordered dict)
# persist_vars: ['var_name', 'var_name'] # List of variables to persist in TODO state
# asciidoc: |
# Some `asciidoc` text to be included in asciidoc guide
# *instead of* description/post_description
# function: my_python_function # Will call the named function for complex tasks
# commands: !Commands # A !Commands object holding commands to execute for this todo
# root_folder: '{{ git_checkout_folder }}' # path to where commands will run
# commands_text: Introduction text to be displayed just before the commands
# enable_execute: true # Set to false to never offer to run commands automatically
# confirm_each_command: true # Set to false to run all commands without prompting
# remove_files: ['file1', 'folder2'] # List of files or folders that must be gone
# logs_prefix: prefix # Lets you prefix logs file names with this string
# commands: # List of !Commands to execute
# - !Command # One single command
# cmd: "ls {{ folder_to_ls }}" # A single command. May reference jinja vars
# # Double spaces in a cmd will trigger multi-line display with continuation char \
# cwd: relative_path # Where to run command, relative to root_folder
# comment: # Will display a # or REM comment above the command in printouts
# vars: {} # Possible to define local vars for this command only
# logfile: my.og # Overrides log file name which may grow very long :)
# tee: false # If true, sends output to console and file
# stdout: false # if true, sends output only to console, not log file
# live: false # If true, sends output live byte-by-byte to console
# redirect: file.txt # Send output to file. Use instead of >
# redirect_append: false # Will cause output to be appended, like >>
# shell: false $ Set to true to use built-in shell commands
# user_input: # An array of !UserInput objects for requesting input from user
# - !UserInput
# prompt: Please enter your gpg key ID, e.g. 0D8D0B93
# name: gpg_id # This will be stored in todo state and can be referenced as {{ todo_id.name }}
# type: int # if no type is given, a string is stored. Supported types are 'int'
# post_description: |
# Some `asciidoc` text (with jinja template support)
# to be printed *after* commands and user_input is done.
# links:
# - http://example.com/list/of/links?to&be&displayed
groups:
- !TodoGroup
id: prerequisites
title: Prerequisites
description: |
Releasing software requires thorough understanding of the process and careful execution,
as it is easy to make mistakes. It also requires an environtment and tools such as gpg
correctly setup. This section makes sure you're in good shape for the job!
todos:
- !Todo
id: read_up
title: Read up on the release process
description: |-
As a Release Manager (RM) you should be familiar with Apache's release policy,
voting rules, create a PGP/GPG key for use with signing and more. Please familiarise
yourself with the resources listed below.
links:
- https://infra.apache.org/release-publishing.html
- https://www.apache.org/legal/release-policy.html
- https://infra.apache.org/release-signing.html
- !Todo
id: tools
title: Necessary tools are installed
description: |
You will need these tools:
* Python v3.4 or later, with dependencies listed in requirements.txt
* Java 11 in $JAVA11_HOME
* gpg
* git
* svn
* asciidoctor (to generate HTML version)
You should also set the $EDITOR environment variable, else we'll fallback to
`vi` on Linux and `notepad.exe` on Windows, and you don't want that :)
function: check_prerequisites
links:
- https://gnupg.org/download/index.html
- https://asciidoctor.org
- !Todo
id: gpg
title: GPG key id is configured
description: |-
To sign the release you need to provide your GPG key ID. This must be
the same key ID that you have registered in your Apache account.
The ID is the last 8 bytes of your key fingerprint, e.g. 0D8D0B93.
* Make sure your gpg key is 4096 bits key or larger
* Upload your key to a key server: pgp.mit.edu or keys.openpgp.org
* Put your GPG key's fingerprint in the `OpenPGP Public Key Primary Fingerprint`
field in your id.apache.org profile
* The tests will complain if your GPG key has not been signed by another Lucene
committer. This makes you a part of the GPG "web of trust" (WoT). Ask a committer
that you know personally to sign your key for you, providing them with the
fingerprint for the key.
You can choose between signing the release with the gpg program or with the
gradle signing plugin. Read about the difference in https://github.com/apache/lucene/blob/main/help/publishing.txt
This wizard can prompt you securely for your passphrase (will not be stored) and pass it on to
buildAndPushRelease in a secure way. However, you can also configure your passphrase in advance
and avoid having to type it in the terminal. This can be done with either a gpg-agent (for gpg tool)
or in `gradle.properties` or an ENV.var (for gradle), See `./gradlew helpPublishing` for details.
function: configure_pgp
links:
- https://infra.apache.org/release-signing.html
- https://infra.apache.org/openpgp.html#apache-wot
- https://id.apache.org
- https://dist.apache.org/repos/dist/release/lucene/KEYS
- https://github.com/apache/lucene/blob/main/help/publishing.txt
- !TodoGroup
id: preparation
title: Prepare for the release
description: Work with the community to decide when the release will happen and what work must be completed before it can happen
todos:
- !Todo
id: decide_github_issues
title: Select issues to be included
description: Set the appropriate "Milestone" in Github for the issues that should be included in the release.
- !Todo
id: fix_build_failures
title: Look into common build failures
description: |
Look over recent build results sent to the builds@lucene.apache.org list and try to address any recurring
failures. It's best to fix common failures now, so they don't pop up later and interfere with release smoke
testing. Build email archives are available at https://lists.apache.org/list.html?builds@lucene.apache.org.
- !Todo
id: decide_branch_date
title: Decide the date for branching
types:
- major
- minor
user_input: !UserInput
prompt: Enter date (YYYY-MM-DD)
name: branch_date
- !Todo
id: decide_freeze_length
title: Decide the length of feature freeze
types:
- major
- minor
user_input: !UserInput
prompt: Enter end date of feature freeze (YYYY-MM-DD)
name: feature_freeze_date
- !TodoGroup
id: branching_versions
title: Create branch (if needed) and update versions
description: Here you'll do all the branching and version updates needed to prepare for the new release version
todos:
- !Todo
id: clean_git_checkout
title: Do a clean git clone to do the release from
description: This eliminates the risk of a dirty checkout
commands: !Commands
root_folder: '{{ release_folder }}'
commands_text: Run these commands to make a fresh clone in the release folder
remove_files:
- '{{ git_checkout_folder }}'
commands:
- !Command
cmd: git clone --progress https://gitbox.apache.org/repos/asf/lucene.git lucene
logfile: git_clone.log
- !Todo
id: gradle_precommit
title: Run gradle precommit and fix issues
depends: clean_git_checkout
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: |-
From the base branch {{ base_branch }} we'll run precommit tests.
Fix any problems that are found by pushing fixes to the branch
and then running this task again. This task will always do `git pull`
before `{{ gradle_cmd }} precommit` so it will catch changes to your branch :)
confirm_each_command: false
commands:
- !Command
cmd: git checkout {{ base_branch }}
stdout: true
- !Command
cmd: git clean -df && git checkout -- .
comment: Make sure checkout is clean and up to date
logfile: git_clean.log
tee: true
- !Command
cmd: git pull --ff-only
stdout: true
- !Command
cmd: "{{ gradle_cmd }} clean check -x test"
- !Todo
id: create_stable_branch
title: Create a new stable branch, off from main
description: In our case we'll create {{ stable_branch }}
types:
- major
depends: clean_git_checkout
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Run these commands to create a stable branch
commands:
- !Command
cmd: git checkout main
tee: true
- !Command
cmd: git pull --ff-only
tee: true
- !Command
cmd: git ls-remote --exit-code --heads origin {{ stable_branch }}
stdout: true
should_fail: true
comment: We expect error code 2 since {{ stable_branch }} does not already exist
- !Command
cmd: git checkout -b {{ stable_branch }}
tee: true
- !Command
cmd: git push --set-upstream origin {{ stable_branch }}
tee: true
- !Todo
id: create_minor_branch
title: Create a new minor branch off the stable branch
description: In our case we'll create {{ release_branch }}
types:
- major
- minor
depends: clean_git_checkout
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Run these commands to create a release branch
commands:
- !Command
cmd: git checkout {{ stable_branch }}
tee: true
- !Command
cmd: git pull --ff-only
tee: true
- !Command
cmd: git ls-remote --exit-code --heads origin {{ release_branch }}
stdout: true
should_fail: true
comment: This command should fail with exit code 2 to verify branch {{ release_branch }} does not already exist
- !Command
cmd: git checkout -b {{ release_branch }}
tee: true
- !Command
cmd: git push --set-upstream origin {{ release_branch }}
tee: true
- !Todo
id: add_version_major
title: Add a new major version on main branch
types:
- major
depends: clean_git_checkout
vars:
next_version: "{{ release_version_major + 1 }}.0.0"
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Run these commands to add the new major version {{ next_version }} to the main branch
commands:
- !Command
cmd: git checkout main
tee: true
- !Command
cmd: python3 -u dev-tools/scripts/addVersion.py {{ next_version }} && {{ gradle_cmd }} tidy
tee: true
- !Command
comment: Make sure the edits done by `addVersion.py` are ok, then push
cmd: git add -u . && git commit -m "Add next major version {{ next_version }}" && git push
logfile: commit-stable.log
post_description: |
Make sure to follow the manual instructions printed by the script:
* Move backcompat oldIndexes to unsupportedIndexes in TestBackwardsCompatibility
* Update IndexFormatTooOldException throw cases
There may be other steps needed as well
- !Todo
id: add_version_minor
title: Add a new minor version on stable and unstable branches
types:
- major
- minor
depends: clean_git_checkout
vars:
next_version: "{{ release_version_major }}.{{ release_version_minor + 1 }}.0"
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Run these commands to add the new minor version {{ next_version }} to the stable and unstable branches
commands:
- !Command
cmd: git checkout {{ stable_branch }}
tee: true
- !Command
cmd: python3 -u dev-tools/scripts/addVersion.py {{ next_version }} && {{ gradle_cmd }} tidy
tee: true
- !Command
comment: Make sure the edits done by `addVersion.py` are ok, then push
cmd: git add -u . && git commit -m "Add next minor version {{ next_version }}" && git push
logfile: commit-stable.log
- !Command
cmd: git checkout main
tee: true
- !Command
cmd: git pull --ff-only
tee: true
- !Command
cmd: python3 -u dev-tools/scripts/addVersion.py {{ next_version }}
tee: true
- !Command
comment: Make sure the edits done by `addVersion.py` are ok, then push
cmd: git add -u . && git commit -m "Add next minor version {{ next_version }}" && git push
logfile: commit-stable.log
- !Todo
id: sanity_check_doap
title: Sanity check the DOAP files
description: |-
Sanity check the DOAP files under `dev-tools/doap/`.
Do they contain all releases less than the one in progress?
TIP: The buildAndPushRelease script run later will check this automatically
links:
- https://projects.apache.org/doap.html
- !Todo
id: jenkins_builds
title: Add Jenkins task for the release branch
description: '...so that builds run for the new branch. Consult the JenkinsReleaseBuilds page.'
types:
- major
- minor
links:
- https://cwiki.apache.org/confluence/display/LUCENEJAVA/JenkinsReleaseBuilds
- !Todo
id: inform_devs
title: Inform Devs of the new Release Branch
description: |-
Send a note to dev@ to inform the committers that the branch
has been created and the feature freeze phase has started.
This is an e-mail template you can use as a basis for
announcing the new branch and feature freeze.
.Mail template
----
To: dev@lucene.apache.org
Subject: New branch and feature freeze for Lucene {{ release_version }}
NOTICE:
Branch {{ release_branch }} has been cut and versions updated to {{ release_version_major }}.{{ release_version_minor + 1 }} on stable branch.
Please observe the normal rules:
* No new features may be committed to the branch.
* Documentation patches, build patches and serious bug fixes may be
committed to the branch. However, you should submit all patches you
want to commit as pull requests first to give others the chance to review
and possibly vote against them. Keep in mind that it is our
main intention to keep the branch as stable as possible.
* All patches that are intended for the branch should first be committed
to the unstable branch, merged into the stable branch, and then into
the current release branch.
* Normal unstable and stable branch development may continue as usual.
However, if you plan to commit a big change to the unstable branch
while the branch feature freeze is in effect, think twice: can't the
addition wait a couple more days? Merges of bug fixes into the branch
may become more difficult.
* Only Github issues with Milestone {{ release_version_major }}.{{ release_version_minor }}
will delay a release candidate build.
----
types:
- major
- minor
- !Todo
id: inform_devs_bugfix
title: Inform Devs about the planned release
description: |-
Send a note to dev@ to inform the committers about the rules for committing to the branch.
This is an e-mail template you can use as a basis for
announcing the rules for committing to the release branch
.Mail template
----
To: dev@lucene.apache.org
Subject: Bugfix release Lucene {{ release_version }}
NOTICE:
I am now preparing for a bugfix release from branch {{ release_branch }}
Please observe the normal rules for committing to this branch:
* Before committing to the branch, reply to this thread and argue
why the fix needs backporting and how long it will take.
* All issues accepted for backporting should be marked with {{ release_version }}
in GitHub, and issues that should delay the release must be marked as Blocker
* All patches that are intended for the branch should first be committed
to the unstable branch, merged into the stable branch, and then into
the current release branch.
* Only GitHub issues or pull requests with milestone {{ release_version }} and
priority "Blocker" will delay a release candidate build.
----
types:
- bugfix
- !Todo
id: draft_release_notes
title: Get a draft of the release notes in place
description: |-
These are typically edited on the Wiki
Clone a page for a previous version as a starting point for your release notes.
Edit the contents of `CHANGES.txt` into a more concise format for public consumption.
Ask on dev@ for input. Ideally the timing of this request mostly coincides with the
release branch creation. It's a good idea to remind the devs of this later in the release too.
NOTE: Do not add every single GitHub PR, but distill the Release note into important changes!
links:
- https://cwiki.apache.org/confluence/display/LUCENE/Release+Notes
- !Todo
id: new_github_versions
title: Add a new version in GitHub for the next release
description: |-
Go to the GitHub milestones and add the new version:
{% if release_type == 'major' -%}
. Change name of version `main ({{ release_version_major }}.0)` into `{{ release_version_major }}.0`
{%- endif %}
. Create a new (unreleased) version `{{ get_next_version }}`
types:
- major
- minor
links:
- https://github.com/apache/lucene/milestones
- !TodoGroup
id: artifacts
title: Build the release artifacts
description: |-
If after the last day of the feature freeze phase no blocking issues are
in GitHub with milestone {{ release_version }}, then it's time to build the
release artifacts, run the smoke tester and stage the RC in svn
depends:
- test
- prerequisites
is_in_rc_loop: true
todos:
- !Todo
id: run_tests
title: Run javadoc tests
depends: clean_git_checkout
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Run some tests not ran by `buildAndPublishRelease.py`
confirm_each_command: false
commands:
- !Command
cmd: git checkout {{ release_branch }}
stdout: true
- !Command
cmd: git clean -df && git checkout -- .
comment: Make sure checkout is clean and up to date
logfile: git_clean.log
tee: true
- !Command
cmd: git pull --ff-only
tee: true
- !Command
cmd: "{{ gradle_cmd }} documentation"
post_description: Check that the task passed. If it failed, commit fixes for the failures before proceeding.
- !Todo
id: clear_gradle_cache
title: Clear the gradle cache
description: |
It is recommended to clean your Gradle cache before building the artifacts.
This ensures that all Gradle dependencies are freshly downloaded,
so we emulate a user that never used the Lucene build system before.
commands: !Commands
root_folder: '{{ home }}'
remove_files: .gradle/caches/modules-2/files-2.1_bak
commands_text: These commands will help you rename the folder so you can get it back later if you wish
commands:
- !Command
cmd: "{{ rename_cmd }} files-2.1 files-2.1_bak"
cwd: .gradle/caches/modules-2
stdout: true
- !Todo
id: build_rc
title: Build the release candidate
depends:
- gpg
- run_tests
vars:
logfile: '{{ [rc_folder, ''logs'', ''buildAndPushRelease.log''] | path_join }}'
git_rev: '{{ current_git_rev }}' # Note, git_rev will be recorded in todo state AFTER completion of commands
git_rev_short: '{{ git_rev | truncate(7,true,"") }}' # Note, git_rev_short will be recorded in todo state AFTER completion of commands
local_keys: '{% if keys_downloaded %} --local-keys "{{ [config_path, ''KEYS''] | path_join }}"{% endif %}'
persist_vars:
- git_rev
- git_rev_short
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: |-
In this step we will build the RC using python script `buildAndPushRelease.py`
We have tried to compile the correct command below, and you can choose whether
to let this script kick it off or execute them in another Terminal window yourself
Note that the build will take a long time. To follow the detailed build
log, you can tail the log file {{ logfile | default("<logfile>") }}.
confirm_each_command: false
remove_files:
- '{{ dist_file_path }}'
commands:
- !Command
cmd: git checkout {{ release_branch }}
tee: true
- !Command
cmd: git clean -df && git checkout -- .
comment: Make sure checkout is clean and up to date
logfile: git_clean.log
tee: true
- !Command
cmd: git pull --ff-only
tee: true
- !Command
cmd: python3 -u dev-tools/scripts/buildAndPushRelease.py {{ local_keys }} --logfile {{ logfile }} --push-local "{{ dist_file_path }}" --rc-num {{ rc_number }} --sign {{ gpg_key | default("<gpg_key_id>", True) }}{% if gpg.use_gradle %} --sign-method-gradle{% endif %}{% if not gpg.prompt_pass %} --gpg-pass-noprompt{% endif %}
comment: "Using {% if gpg.use_gradle %}gradle{% else %}gpg command{% endif %} for signing.{% if gpg.prompt_pass %} Remember to type your GPG pass-phrase at the prompt!{% endif %}"
logfile: build_rc.log
tee: true
- !Todo
id: smoke_tester
title: Run the smoke tester
depends: build_rc
vars:
dist_folder: lucene-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}
dist_path: '{{ [dist_file_path, dist_folder] | path_join }}'
tmp_dir: '{{ [rc_folder, ''smoketest''] | path_join }}'
local_keys: '{% if keys_downloaded %} --local-keys "{{ [config_path, ''KEYS''] | path_join }}"{% endif %}'
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Here we'll smoke test the release by 'downloading' the artifacts, running the tests, validating GPG signatures etc.
remove_files:
- '{{ tmp_dir }}'
commands:
- !Command
cmd: python3 -u dev-tools/scripts/smokeTestRelease.py {{ local_keys }} --tmp-dir "{{ tmp_dir }}" file://{{ dist_path | expanduser }}
logfile: smoketest.log
- !Todo
id: import_svn
title: Import artifacts into SVN
description: |
Here we'll import the artifacts into Subversion.
depends: smoke_tester
vars:
dist_folder: lucene-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}
dist_path: '{{ [dist_file_path, dist_folder] | path_join }}'
dist_url: '{{ dist_url_base }}/{{ dist_folder}}'
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Have your Apache credentials handy, you'll be prompted for your password
commands:
- !Command
cmd: svn -m "Lucene {{ release_version }} RC{{ rc_number }}" import {{ dist_path }} {{ dist_url }}
logfile: import_svn.log
tee: true
- !Todo
id: verify_staged
title: Verify staged artifacts
description: |
A lightweight smoke testing which downloads the artifacts from stage
area and checks hash and signatures, but does not re-run all tests.
depends: import_svn
vars:
dist_folder: lucene-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}
dist_url: '{{ dist_url_base }}/{{ dist_folder}}'
tmp_dir: '{{ [rc_folder, ''smoketest_staged''] | path_join }}'
local_keys: '{% if keys_downloaded %} --local-keys "{{ [config_path, ''KEYS''] | path_join }}"{% endif %}'
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Here we'll verify that the staged artifacts are downloadable and hash/signatures match.
remove_files:
- '{{ tmp_dir }}'
commands:
- !Command
cmd: python3 -u dev-tools/scripts/smokeTestRelease.py {{ local_keys }} --download-only --tmp-dir "{{ tmp_dir }}" {{ dist_url }}
logfile: smoketest_staged.log
- !TodoGroup
id: voting
title: Hold the vote and sum up the results
description: These are the steps necessary for the voting process. Read up on the link first!
is_in_rc_loop: true
todos:
- !Todo
id: initiate_vote
title: Initiate the vote
depends: verify_staged
description: |
If the smoke test passes against the staged artifacts, send an email to the dev mailing list announcing the release candidate.
.Mail template
----
To: dev@lucene.apache.org
Subject: [VOTE] Release Lucene {{ release_version }} RC{{ rc_number }}
Please vote for release candidate {{ rc_number }} for Lucene {{ release_version }}
The artifacts can be downloaded from:
{{ dist_url_base }}/lucene-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}
You can run the smoke tester directly with this command:
python3 -u dev-tools/scripts/smokeTestRelease.py \
{{ dist_url_base }}/lucene-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}
The vote will be open for at least 72 hours i.e. until {{ vote_close }}.
[ ] +1 approve
[ ] +0 no opinion
[ ] -1 disapprove (and reason why)
Here is my +1
----
{% if vote_close_72h_holidays %}
[IMPORTANT]
====
The voting period contains one or more holidays. Please consider extending the vote deadline.
{% for holiday in vote_close_72h_holidays %}* {{ holiday }}
{% endfor %}
====
{%- endif %}
vars:
vote_close: '{{ vote_close_72h }}'
vote_close_epoch: '{{ vote_close_72h_epoch }}'
persist_vars:
- vote_close
- vote_close_epoch
function: create_ical
links:
- https://www.apache.org/foundation/voting.html
- !Todo
id: end_vote
title: End vote
depends: initiate_vote
description: |
At the end of the voting deadline, count the votes and send RESULT message to the mailing list.
{% set vote_close_epoch = initiate_vote.vote_close_epoch | int %}
{% if epoch < vote_close_epoch %}
WARNING: The planned voting deadline {{ initiate_vote.vote_close }} has not yet passed
{% else %}
The planned 72h voting deadline {{ initiate_vote.vote_close }} has passed.
{% endif %}
asciidoc: |
(( template=vote_macro ))
Note down how many votes were cast, summing as:
* Binding PMC-member +1 votes
* Non-binding +1 votes
* Neutral +/-0 votes
* Negative -1 votes
You need 3 binding +1 votes and more +1 than -1 votes for the release to happen.
A release cannot be vetoed, see more in provided links.
Here are some mail templates for successful and failed vote results with sample numbers:
{{ end_vote_result(3,1,0,2) }}
{{ end_vote_result(3,1,0,4) }}
{{ end_vote_result(2,9,0,0) }}
user_input:
- !UserInput
type: int
prompt: Number of binding +1 votes (PMC members)
name: plus_binding
- !UserInput
type: int
prompt: Number of other +1 votes
name: plus_other
- !UserInput
type: int
prompt: Number of 0 votes
name: zero
- !UserInput
type: int
prompt: Number of -1 votes
name: minus
post_description: |
(( template=vote_logic ))
(( template=vote_macro ))
{% if passed -%}
Congratulations! The vote has passed.
{% if minus > 0 %}
However, there were negative votes. A release cannot be vetoed, and as long as
there are more positive than negative votes you can techically release
the software. However, please review the negative votes and consider
a re-spin.
{% endif %}
{%- endif %}
{{ end_vote_result(plus_binding,plus_other,zero,minus) }}
links:
- https://www.apache.org/foundation/voting.html
- !TodoGroup
id: publish
title: Publishing to the ASF Distribution Directory
description: Once the vote has passed, the release may be published to the ASF Distribution Directory and to Maven Central.
todos:
- !Todo
id: tag_release
title: Tag the release
description: Tag the release from the same revision from which the passing release candidate's was built
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: This will tag the release in git
logs_prefix: tag_release
commands:
- !Command
cmd: git tag -a releases/lucene/{{ release_version }} -m "Lucene {{ release_version }} release" {{ build_rc.git_rev | default("<git_rev>", True) }}
logfile: git_tag.log
tee: true
- !Command
cmd: git push origin releases/lucene/{{ release_version }}
logfile: git_push_tag.log
tee: true
- !Todo
id: rm_staged_mvn
title: Delete mvn artifacts from staging repo
vars:
dist_folder: lucene-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}
dist_path: '{{ [dist_file_path, dist_folder] | path_join }}'
dist_stage_url: '{{ dist_url_base }}/{{ dist_folder}}'
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
confirm_each_command: false
commands_text: This will remove maven artifacts so they do not end up in the Distribution Directory
commands:
- !Command
cmd: svn rm -m "Delete the lucene maven artifacts" {{ dist_stage_url }}/lucene/maven
logfile: svn_rm_mvn_lucene.log
tee: true
- !Todo
id: mv_to_release
title: Move release artifacts to release repo
vars:
dist_folder: lucene-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}
dist_stage_url: '{{ dist_url_base }}/{{ dist_folder}}'
dist_release_url: https://dist.apache.org/repos/dist/release/lucene
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
confirm_each_command: false
commands_text: This will move the new release artifacts from staging repo to the release repo
commands:
- !Command
cmd: svn move -m "Move Lucene {{ release_version }} RC{{ rc_number }} to release repo" {{ dist_stage_url }}/lucene {{ dist_release_url }}/java/{{ release_version }}
logfile: svn_mv_lucene.log
tee: true
- !Command
cmd: svn rm -m "Clean up the RC folder for {{ release_version }} RC{{ rc_number }}" {{ dist_url_base }}/lucene-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}
logfile: svn_rm_containing.log
comment: Clean up containing folder on the staging repo
tee: true
post_description: 'Note at this point you will see the Jenkins job "Lucene-SmokeRelease-main" begin to fail, until you run the "Generate Backcompat Indexes" '
- !Todo
id: stage_maven
title: Stage the maven artifacts for publishing
vars:
git_sha: '{{ build_rc.git_rev_short | default("<git_sha>", True) }}'
dist_folder: lucene-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
confirm_each_command: true
commands_text: In the source checkout do the following (note that this step will prompt you for your Apache LDAP credentials)
commands:
- !Command
cmd: java dev-tools/scripts/StageArtifacts.java --user {{ gpg.apache_id }} --description "{{ 'Apache Lucene ', release_version, ' (commit ', git_sha, ')' }}" "{{ [dist_file_path, dist_folder, 'lucene', 'maven'] | path_join }}"
tee: true
logfile: publish_lucene_maven.log
post_description: The artifacts are not published yet, please proceed with the next step to actually publish!
- !Todo
id: publish_maven
depends: stage_maven
title: Publish the staged maven artifacts
vars:
git_sha: '{{ build_rc.git_rev_short | default("<git_sha>", True) }}'
description: |
Once you have transferred all maven artifacts to repository.apache.org,
you will need to do some manual steps to actually release them to Maven Central:
* Release the staging repository
. Log in to https://repository.apache.org/ with your ASF credentials
. Select "Staging Repositories" under "Build Promotion" from the navigation bar on the left
. Select the staging repository named, "Apache Lucene {{ release_version }} (commit {{ git_sha }})"
. Click on the "Release" button above the repository list, then enter a description when prompted, e.g. "Lucene {{ release_version }}".
Maven central should show the release after a short while
links:
- https://repository.apache.org/index.html
- !Todo
id: check_distribution_directory
depends: publish_maven
title: Check that artifacts are available
function: check_artifacts_available
description: |
The task will attempt to fetch https://dlcdn.apache.org/lucene/java/{{ release_version }}/lucene-{{ release_version }}-src.tgz.asc
to validate ASF repo, and https://repo1.maven.org/maven2/org/apache/lucene/lucene-core/{{ release_version }}/lucene-core-{{ release_version }}.jar.asc
to validate Maven repo.
If the check fails, please re-run the task, until it succeeds.
- !TodoGroup
id: website
title: Update the website
description: |
For every release, we publish docs on the website, we need to update the
download pages etc. The website is hosted in https://github.com/apache/lucene-site
but the Javadocs are pushed to SVN and then included in the main site through links.
todos:
- !Todo
id: website_docs
title: Publish docs, changes and javadocs
description: |
Ensure your refrigerator has at least 2 beers - the svn import operation can take a while,
depending on your upload bandwidth. We'll publish this directly to the production tree. At
the end of the task, the two links below shall work.
links:
- http://lucene.apache.org/core/{{ version }}
vars:
release_tag: releases/lucene/{{ release_version }}
version: "{{ release_version_major }}_{{ release_version_minor }}_{{ release_version_bugfix }}"
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Build the documentation and add it to SVN production tree
commands:
- !Command
cmd: git fetch && git checkout {{ release_tag }}
comment: Checkout the release branch
logfile: checkout-release-tag.log
tee: true
- !Command
cmd: "{{ gradle_cmd }} documentation -Dversion.release={{ release_version }}"
comment: Build documentation
- !Command
cmd: svn -m "Add docs, changes and javadocs for Lucene {{ release_version }}" import {{ git_checkout_folder }}/lucene/documentation/build/site https://svn.apache.org/repos/infra/sites/lucene/core/{{ version }}
logfile: add-docs-lucene.log
comment: Add docs for Lucene
- !Todo
id: website_git_clone
title: Do a clean git clone of the website repo
description: This is where we'll commit later updates for the website.
commands: !Commands
root_folder: '{{ release_folder }}'
commands_text: Run this command to clone the website git repo
remove_files:
- '{{ git_website_folder }}'
commands:
- !Command
cmd: git clone --progress https://gitbox.apache.org/repos/asf/lucene-site.git lucene-site
logfile: website_git_clone.log
- !Todo
id: website_update_versions
title: Update website versions
depends: website_git_clone
vars:
release_tag: releases/lucene/{{ release_version }}
description: |
We need to update the website so that the download pages list the new release, and the
"latest" javadoc links point to the new release.
Fortunately the only thing you need to change is a few variables in `pelicanconf.py`.
If you release a current latest release, change the `LUCENE_LATEST_RELEASE` and `LUCENE_LATEST_RELEASE_DATE`
variables.
If you relese a bugfix release for previous version, then change the `LUCENE_PREVIOUS_MAJOR_RELEASE` variable.
commands: !Commands
root_folder: '{{ git_website_folder }}'
commands_text: Edit pelicanconf.py to update version numbers
commands:
- !Command
cmd: "{{ editor }} pelicanconf.py"
comment: Edit the pelicanconf.file
stdout: true
- !Command
cmd: git commit -am "Update version variables for release {{ release_version }}"
logfile: commit.log
stdout: true
post_description: |
You will push and verify all changes in a later step
- !Todo
id: prepare_announce_lucene
title: Author the Lucene release news
depends: website_git_clone
description: |
Edit a news text for the Lucene website. This text will be the basis for the release announcement email later.
This step will open an editor with a template. You will need to copy/paste the final release announcement text
from the Wiki page and format it as Markdown.
function: prepare_announce_lucene
commands: !Commands
root_folder: '{{ git_website_folder }}'
commands_text: |
Copy the Lucene announcement from https://cwiki.apache.org/confluence/display/LUCENE/Release+Notes
You have to exit the editor after edit to continue.
commands:
- !Command
cmd: "{{ editor }} {{ lucene_news_file }}"
comment: Edit the for Lucene announcement news
stdout: true
- !Command
cmd: git add . && git commit -m "Adding Lucene news for release {{ release_version }}"
logfile: commit.log
stdout: true
post_description: |
You will push and verify all changes in a later step
- !Todo
id: update_other
title: Update rest of webpage
depends: website_update_versions
description: |
Update the rest of the web page. Please review all files in the checkout
and consider if any need change based on what changes there are in the
release you are doing. Things to consider:
* System requirements
* Quickstart and tutorial?
commands: !Commands
root_folder: '{{ git_website_folder }}'
commands_text: |
We'll open an editor on the root folder of the site checkout
You have to exit the editor after edit to continue.
commands:
- !Command
cmd: "{{ editor }} ."
comment: Open an editor on the root folder
stdout: true
- !Command
cmd: git commit -am "Other website changes for release {{ release_version }}"
comment: Commit the other changes
logfile: commit.log
stdout: true
- !Todo
id: stage_website
title: Stage the website changes
depends:
- prepare_announce_lucene
description: |
Push the website changes to 'main' branch, and check the staging site.
You will get a chance to preview the diff of all changes before you push.
If you need to do changes, do the changes (e.g. by re-running previous step 'Update rest of webpage')
and commit your changes. Then re-run this step and push when everything is OK.
commands: !Commands
root_folder: '{{ git_website_folder }}'
commands_text: |
Verify that changes look good, and then publish.
You have to exit the editor after review to continue.
commands:
- !Command
cmd: git checkout main && git status
stdout: true
- !Command
cmd: git diff
redirect: "{{ [release_folder, 'website.diff'] | path_join }}"
comment: Make a diff of all edits. Will open in next step
- !Command
cmd: "{{ editor }} {{ [release_folder, 'website.diff'] | path_join }}"
comment: View the diff of the website changes. Abort if you need to do changes.
stdout: true
- !Command
cmd: git push origin
comment: Push all changes
logfile: push-website.log
post_description: |
Wait a few minutes for the build to happen. You can follow the site build at
https://ci2.apache.org/#/builders/3 and view the staged site at
https://lucene.staged.apache.org Verify that correct links and versions are mentioned in
download pages, download buttons etc. If you find anything wrong, then commit and push any
changes and check again. You may find that the publish fails, leaving a directory listing
instead a beautiful website. If this happens, check the "builder" link and click through into
its details to find possible error messages produced by the website publication process. You
may have produced malformed Markdown. Or the website publish may just fail for some reason out
of your control. If this happens, you can attempt to retrigger the publishing with some
innocuous changes. Next step is to merge the changes to branch 'production' in order to
publish the site. Before doing this, you may want to replenish your stock of beers, or get
stronger stuff.
links:
- https://ci2.apache.org/#/builders/3
- https://lucene.staged.apache.org
- !Todo
id: publish_website
title: Publish the website changes
depends:
- stage_website
description: |
Push the website changes to 'production' branch. This will build and publish the live site on
https://lucene.apache.org
commands: !Commands
root_folder: '{{ git_website_folder }}'
commands:
- !Command
cmd: git checkout production && git pull --ff-only
stdout: true
- !Command
cmd: git merge main
stdout: true
- !Command
cmd: git push origin
comment: Push all changes to production branch
logfile: push-website.log
post_description: |
Wait a few minutes for the build to happen. You can follow the site build at https://ci2.apache.org/#/builders/3
Verify on https://lucene.apache.org that the site is OK. It really should be, but see staging
site publication instructions for possible debugging/recovery options if it is not.
You can now also verify that http://lucene.apache.org/core/api/core/ redirects to the latest version
links:
- https://ci2.apache.org/#/builders/3
- https://lucene.apache.org
- http://lucene.apache.org/core/api/core/
- !Todo
id: update_doap
title: Update the DOAP file
description: |
Update the Lucene DOAP RDF file on the unstable, stable and release branches to
reflect the new versions (note that the website .htaccess file redirects from their
canonical URLs to their locations in the Lucene Git source repository - see
dev-tools/doap/README.txt for more info)
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Edit DOAP files
commands:
- !Command
cmd: git checkout main && git pull --ff-only
stdout: true
comment: Goto main branch
- !Command
cmd: "{{ editor }} dev-tools/doap/lucene.rdf"
comment: Edit Lucene DOAP, add version {{ release_version }}
stdout: true
- !Command
cmd: git add dev-tools/doap/lucene.rdf && git commit -m "DOAP changes for release {{ release_version }}"
logfile: commit.log
stdout: true
- !Command
cmd: git push origin
logfile: push.log
stdout: true
comment: Push the main branch
- !Command
cmd: "git checkout {{ stable_branch }} && git pull --ff-only"
stdout: true
comment: Checkout the stable branch
- !Command
cmd: "git cherry-pick main"
logfile: commit.log
stdout: true
comment: Cherrypick the DOAP changes from main onto the stable branch.
- !Command
cmd: git show HEAD
stdout: true
comment: Ensure the only change is adding the new version.
- !Command
cmd: git push origin
logfile: push.log
stdout: true
comment: Push the stable branch
- !Command
cmd: "git checkout {{ release_branch }} && git pull --ff-only"
stdout: true
comment: Checkout the release branch
- !Command
cmd: "git cherry-pick {{ stable_branch }}"
logfile: commit.log
stdout: true
comment: Cherrypick the DOAP changes from the stable branch onto the release branch.
- !Command
cmd: git show HEAD
stdout: true
comment: Ensure the only change is adding the new version.
- !Command
cmd: git push origin
logfile: push.log
stdout: true
comment: Push the release branch
- !Todo
id: create_github_release
title: Create a Github Release
description: |
Create a github release named "{{ release_version }}" based off of the git tag "{{ release_version }}".
You can use the previous releases as a template. No artifacts need to be manually uploaded.
(You can hit "edit" on a previous release, to get the markdown version of the notes to copy.)
links:
- https://github.com/apache/lucene/releases
- !TodoGroup
id: announce
title: Announce the release
description: |
For feature releases, your announcement should describe the main features included
in the release. *Send the announce as Plain-text email, not HTML.*
This step will generate email templates based on the news files you edited earler for the website.
Do any last-minute necessary edits to the text as you copy it over to the email.
todos:
- !Todo
id: announce_lucene
title: Announce the Lucene release (@l.a.o)
description: |
(( template=announce_lucene_mail ))
- !Todo
id: setup_pgp_mail
title: Setup your mail client for PGP
description: |
The announce mail to `announce@apache.org` should be cryptographically signed.
Make sure you have a PGP enabled email client with your apache key installed.
There are plugins for popular email programs, as well as browser plugins for webmail.
See links for help on how to setup your email client for PGP.
If you prefer to sign the announcements manually rather than using a plugin,
you can do so from the command line and then copy the output into your mail program.
gpg --output - --clearsign lucene_announce.txt
links:
- https://www.openpgp.org/software/
- https://ssd.eff.org/en/module/how-use-pgp-mac-os-x
- https://ssd.eff.org/en/module/how-use-pgp-linux
- https://ssd.eff.org/en/module/how-use-pgp-windows
- https://www.openpgp.org/software/mailvelope/
- !Todo
id: announce_lucene_sig
title: Announce the Lucene release (announce@a.o)
description: |
(( template=announce_lucene_sign_mail ))
- !Todo
id: add_to_wikipedia
title: Add the new version to Wikipedia
description: |
Go to Wikipedia and edit the page to include the new release.
Major versions should have a small new paragraph under 'History'.
If you know other languages than English, edit those as well.
links:
- https://en.wikipedia.org/wiki/Apache_Lucene
- !Todo
id: add_to_apache_reporter
title: Add the new version to the Apache Release Reporter
description: |
Go to the Apache Release Reporter and add a release for lucene. (Ask a PMC member to help if you're not one)
Fill in the same date that you used for the release in previous steps.
Do not use a product name prefix for the version, as this is the main release of the lucene PMC.
Just use the version of this release: {{ release_version }}
links:
- https://reporter.apache.org/addrelease.html?lucene
- !TodoGroup
id: post_release
title: Tasks to do after release.
description: There are many more tasks to do now that the new version is out there, so hang in there for a few more hours.
todos:
- !Todo
id: add_version_bugfix
title: Add a new bugfix version to stable and unstable branches
types:
- bugfix
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: |
Update versions on main and stable branch.
You may have to hand-edit some files before commit, so go slowly :)
confirm_each_command: true
commands:
- !Command
cmd: git checkout main && git pull --ff-only && git clean -df && git checkout -- .
comment: Go to main branch
logfile: checkout-main.log
- !Command
cmd: python3 -u dev-tools/scripts/addVersion.py {{ release_version }} && {{ gradle_cmd }} tidy
logfile: addversion-main.log
- !Command
cmd: git diff
logfile: diff-main.log
tee: true
- !Command
cmd: git add -u . && git commit -m "Add bugfix version {{ release_version }}" && git push
logfile: commit-main.log
- !Command
cmd: git checkout {{ stable_branch }} && git pull --ff-only && git clean -df && git checkout -- .
logfile: checkout-stable.log
comment: Now the same for the stable branch
- !Command
cmd: python3 -u dev-tools/scripts/addVersion.py {{ release_version }} && {{ gradle_cmd }} tidy
logfile: addversion-stable.log
- !Command
cmd: git diff
logfile: diff-stable.log
tee: true
- !Command
cmd: git add -u . && git commit -m "Add bugfix version {{ release_version }}" && git push
logfile: commit-stable.log
- !Todo
id: synchronize_changes
title: Synchronize CHANGES.txt
description: |
Copy the CHANGES.txt section for this release back to the stable and unstable branches'
CHANGES.txt files, removing any duplicate entries, but only from sections for as-yet
unreleased versions; leave intact duplicate entries for already-released versions.
There is a script to generate a regex that will match issues fixed in a release:
`releasedJirasRegex.py`. The following examples will print regexes matching all issues
fixed in {{ release_version }}, which can then be used to find duplicates in unreleased
version sections of the corresponding CHANGES.txt files.
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Synchronize CHANGES.txt
commands:
- !Command
cmd: git checkout {{ release_branch }}
comment: Go to release branch
logfile: checkout-release.log
stdout: true
- !Command
cmd: python3 -u -B dev-tools/scripts/releasedJirasRegex.py {{ release_version }} lucene/CHANGES.txt
tee: true
comment: Find version regexes
- !Command
cmd: git checkout main && git pull --ff-only && git clean -df && git checkout -- .
comment: Go to main branch
logfile: checkout-main.log
- !Command
cmd: "{{ editor }} lucene/CHANGES.txt"
comment: Edit CHANGES.txt for main branch, do necessary changes
stdout: true
- !Command
cmd: git add -u . && git commit -m "Sync CHANGES for {{ release_version }}" && git push
logfile: commit-main.log
- !Command
cmd: git checkout {{ stable_branch }} && git pull --ff-only && git clean -df && git checkout -- .
comment: Go to stable branch
logfile: checkout-stable.log
- !Command
cmd: "{{ editor }} lucene/CHANGES.txt"
comment: Edit CHANGES.txt for stable branch, do necessary changes
stdout: true
- !Command
cmd: git add -u . && git commit -m "Sync CHANGES for {{ release_version }}" && git push
logfile: commit-stable.log
- !Todo
id: increment_release_version
title: Add the next version on release branch
description: Add the next version after the just-released version on the release branch
depends: publish_maven
vars:
next_version: "{{ release_version_major }}.{{ release_version_minor }}.{{ release_version_bugfix + 1 }}"
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Run these commands to add the new bugfix version {{ next_version }} to the release branch
commands:
- !Command
cmd: git checkout {{ release_branch }}
tee: true
- !Command
cmd: python3 -u dev-tools/scripts/addVersion.py {{ next_version }} && {{ gradle_cmd }} tidy
tee: true
- !Command
cmd: git diff
logfile: diff.log
comment: Check the git diff before committing. Do any edits if necessary
tee: true
- !Command
cmd: git add -u . && git commit -m "Add next bugfix version {{ next_version }}" && git push
logfile: commit-stable.log
- !Todo
id: backcompat_release
title: Generate Backcompat Indexes for release branch
description: |
After each version of Lucene is released, compressed CFS, non-CFS, and sorted indexes created with
the newly released version are added to `lucene/backwards-codecs/src/test/org/apache/lucene/index/`,
for use in testing backward index compatibility via org.apache.lucene.index.TestBackwardsCompatibility,
which is also located under the `backwards-codecs/` module. There are also three indexes created only
with major Lucene versions: moreterms, empty, and dvupdates. These indexes are created via methods
on `TestBackwardsCompatibility` itself - see comments in the source for more information.
There is a script (`dev-tools/scripts/addBackcompatIndexes.py`) that automates most of the process.
It downloads the source for the specified release; generates indexes for the current release using
`TestBackwardsCompatibility`; compresses the indexes and places them in the correct place in the source
tree; modifies TestBackwardsCompatibility.java to include the generated indexes in the list of indexes
to test; and then runs `TestBackwardsCompatibility`.
In this and the next two steps we'll guide you through using this tool on each of the branches.
depends:
- increment_release_version
vars:
temp_dir: "{{ [release_folder, 'backcompat'] | path_join }}"
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Run these commands to add back-compat indices to release branch
commands:
- !Command
cmd: git checkout {{ release_branch }} && git pull --ff-only && git clean -df && git checkout -- .
tee: true
logfile: checkout.log
- !Command
cmd: "{{ gradle_cmd }} clean"
- !Command
cmd: python3 -u dev-tools/scripts/addBackcompatIndexes.py --no-cleanup --temp-dir {{ temp_dir }} {{ release_version }} && git add lucene/backward-codecs/src/test/org/apache/lucene/backward_index/
logfile: add-backcompat.log
- !Command
cmd: git diff --staged
comment: Check the git diff before committing
tee: true
- !Command
cmd: git commit -m "Add back-compat indices for {{ release_version }}" && git push
logfile: commit.log
- !Todo
id: backcompat_stable
title: Generate Backcompat Indexes for stable branch
description: |
Now generate back-compat for stable branch ({{ stable_branch }})
depends:
- increment_release_version
vars:
temp_dir: "{{ [release_folder, 'backcompat'] | path_join }}"
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Run these commands to add back-compat indices to {{ stable_branch }}
commands:
- !Command
cmd: git checkout {{ stable_branch }} && git pull --ff-only && git clean -df && git checkout -- .
tee: true
logfile: checkout.log
- !Command
cmd: "{{ gradle_cmd }} clean"
- !Command
cmd: python3 -u dev-tools/scripts/addBackcompatIndexes.py --no-cleanup --temp-dir {{ temp_dir }} {{ release_version }} && git add lucene/backward-codecs/src/test/org/apache/lucene/backward_index/
logfile: add-backcompat.log
- !Command
cmd: git diff --staged
comment: Check the git diff before committing
tee: true
- !Command
cmd: git commit -m "Add back-compat indices for {{ release_version }}" && git push
logfile: commit.log
- !Todo
id: backcompat_main
title: Generate Backcompat Indexes for unstable branch
description: |
Now generate back-compat for unstable (main) branch.
Note that this time we do not specify `--no-cleanup` meaning the tmp folder will be deleted
depends:
- increment_release_version
vars:
temp_dir: "{{ [release_folder, 'backcompat'] | path_join }}"
version: "{{ set_java_home(main_version) }}"
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: Run these commands to add back-compat indices to main
commands:
- !Command
cmd: git checkout main && git pull --ff-only && git clean -df && git checkout -- .
tee: true
logfile: checkout.log
- !Command
cmd: "{{ gradle_cmd }} clean"
- !Command
cmd: python3 -u dev-tools/scripts/addBackcompatIndexes.py --temp-dir {{ temp_dir }} {{ release_version }} && git add lucene/backward-codecs/src/test/org/apache/lucene/backward_index/
logfile: add-backcompat.log
- !Command
cmd: git diff --staged
comment: Check the git diff before committing
tee: true
- !Command
cmd: git commit -m "Add back-compat indices for {{ release_version }}" && git push
logfile: commit.log
post_description: |
When doing a major version release, eg. 8.0.0, you might also need to reenable some
backward compatibility tests for corner cases. To find them, run grep -r assume
lucene/backward-codecs/, which should find tests that have been disabled on main
because there was no released Lucene version to test against.
{{ set_java_home(release_version) }}
- !Todo
id: github_change_unresolved
title: Remove milestone for unresolved
description: |-
Go to GitHub to update all open issues assigned to milestone _{{ release_version }}_.
. Open https://github.com/apache/lucene/milestones/{{ release_version }}
. Remove the milestone from all issues and pull requests that are still open.
links:
- https://github.com/apache/lucene/milestones/{{ release_version }}
- !Todo
id: github_milestone_close
depends: github_change_unresolved
title: Mark milestone as closed in Github
description: |-
Go to https://github.com/apache/lucene/milestones.
. Find version {{ release_version }}, click "edit" under the progress bar
. Set the "Due Date" to the release date of this version
. Click "Close milestone"
links:
- https://github.com/apache/lucene/milestones
- !Todo
id: new_github_versions_bugfix
title: Add a new milestone in GitHub for the next release
description: |-
Go to GitHub milestones and add the new version {{ get_next_version }}`.
types:
- bugfix
links:
- https://github.com/apache/lucene/milestones
- !Todo
id: stop_promoting_old
title: Stop promoting old releases
description: |
Shortly after new releases are first published, they are automatically copied to the archives.
Only the latest point release from each active branch should be kept under the Lucene PMC
svnpubsub area `dist/releases/lucene/`. Older releases can be
safely deleted, since they are already backed up in the archives.
Currently these versions exist in the distribution directory:
*{{ mirrored_versions|join(', ') }}*
The commands below will remove old versions automatically. If this suggestion is wrong,
please do *not* execute the commands automatically, but edit the command and run manually.
Versions to be deleted from the distribution directory are:
*{{ mirrored_versions_to_delete|join(', ') }}*
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: |
Run these commands to delete proposed versions from distribution directory.
WARNING: Validate that the proposal is correct!
commands:
- !Command
cmd: |
svn rm -m "Stop publishing old Lucene releases"{% for ver in mirrored_versions_to_delete %} https://dist.apache.org/repos/dist/release/lucene/java/{{ ver }}{% endfor %}
logfile: svn-rm-lucene.log