mirror of https://github.com/apache/lucene.git
1575 lines
67 KiB
YAML
1575 lines
67 KiB
YAML
#
|
||
# 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 Candidata (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, general@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 %}
|
||
|
||
|
||
Note: The Apache Software Foundation uses an extensive mirroring network for
|
||
distributing releases. It is possible that the mirror you are using may not have
|
||
replicated the release yet. If that is the case, please try another mirror.
|
||
This also applies to Maven access.
|
||
# 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
|
||
# {{ todi_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://www.apache.org/dev/release-publishing.html
|
||
- https://www.apache.org/legal/release-policy.html
|
||
- https://infra.apache.org/release-signing.html
|
||
- https://cwiki.apache.org/confluence/display/LUCENE/ReleaseTodo
|
||
- !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 the MIT key server, pgp.mit.edu
|
||
* Put you 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.
|
||
function: configure_pgp
|
||
links:
|
||
- http://www.apache.org/dev/release-signing.html
|
||
- http://www.apache.org/dev/openpgp.html#apache-wot
|
||
- https://id.apache.org
|
||
- https://dist.apache.org/repos/dist/release/lucene/KEYS
|
||
- !Todo
|
||
id: jira_permissions
|
||
title: Obtain the neccessary permissions for Apache Jira
|
||
description: |-
|
||
If you are not a PMC member and this is your first time as RM, please ask to be granted extra permissions in Jira in order to complete all steps of the release.
|
||
|
||
If you are a PMC member, you will already have the necessary permissions.
|
||
links:
|
||
- https://issues.apache.org/jira/projects/LUCENE
|
||
- !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_jira_issues
|
||
title: Select JIRA issues to be included
|
||
description: Set the appropriate "Fix Version" in JIRA for the issues that should be included in the release.
|
||
- !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 lenght 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 }} localSettings"
|
||
- !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 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 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 }}
|
||
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 branch
|
||
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 branch
|
||
commands:
|
||
- !Command
|
||
cmd: git checkout {{ stable_branch }}
|
||
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 to Jira first to give others the chance to review
|
||
and possibly vote against the patch. 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 Jira issues with Fix version {{ release_version_major }}.{{ release_version_minor }} and priority "Blocker" 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 JIRA, 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 Jira issues with Fix version {{ 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 JIRA issue, but distill the Release note into important changes!
|
||
links:
|
||
- https://cwiki.apache.org/confluence/display/LUCENE/Release+Notes
|
||
- !Todo
|
||
id: new_jira_versions
|
||
title: Add a new version in JIRA for the next release
|
||
description: |-
|
||
Go to the JIRA "Manage Versions" Administration pages 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://issues.apache.org/jira/plugins/servlet/project-config/LUCENE/versions
|
||
- !TodoGroup
|
||
id: artifacts
|
||
title: Build the release artifacts
|
||
description: |-
|
||
If after the last day of the feature freeze phase no blocking issues are
|
||
in JIRA with "Fix Version" {{ 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: "{{ 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
|
||
local_keys: '{% if keys_downloaded %} --local-keys "{{ [config_path, ''KEYS''] | path_join }}"{% endif %}'
|
||
persist_vars:
|
||
- git_rev
|
||
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) }}
|
||
comment: "NOTE: Remember to type your GPG pass-phrase at the prompt!"
|
||
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: https://dist.apache.org/repos/dist/dev/lucene/{{ 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: https://dist.apache.org/repos/dist/dev/lucene/{{ 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:
|
||
https://dist.apache.org/repos/dist/dev/lucene/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 \
|
||
https://dist.apache.org/repos/dist/dev/lucene/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: https://dist.apache.org/repos/dist/dev/lucene/{{ 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: https://dist.apache.org/repos/dist/dev/lucene/{{ 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 }}" https://dist.apache.org/repos/dist/dev/lucene/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:
|
||
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: ant clean stage-maven-artifacts -Dmaven.dist.dir={{ [dist_file_path, dist_folder, 'lucene', 'maven'] | path_join }} -Dm2.repository.id=apache.releases.https -Dm2.repository.url={{ m2_repository_url }}
|
||
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
|
||
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:
|
||
|
||
* Close 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 containing the Lucene artifacts
|
||
. Click on the "Close" button above the repository list, then enter a description when prompted, e.g. "Lucene {{ release_version }} RC{{ rc_number }}"
|
||
* The system will now spend some time validating the artifacts. Grab a coke and come back.
|
||
* Release the Lucene artifacts
|
||
. Wait and keep clicking refresh until the "Release" button becomes available
|
||
. 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://wiki.apache.org/lucene-java/PublishMavenArtifacts
|
||
- 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 }}.pom.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 previos 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.
|
||
|
||
Next step is to merge the changes to branch 'production' in order to publish the site.
|
||
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.
|
||
|
||
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 files
|
||
description: |
|
||
Update the DOAP RDF files 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
|
||
- !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.
|
||
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 }}
|
||
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 }}
|
||
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 JIRAs fixed in a release:
|
||
`releasedJirasRegex.py`. The following examples will print regexes matching all JIRAs
|
||
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 }}
|
||
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/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/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/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: jira_release
|
||
title: Mark version as released in JIRA
|
||
description: |-
|
||
Go to the JIRA "Manage Versions" Administration pages.
|
||
|
||
. Next to version {{ release_version }}, click the gear pop-up menu icon and choose "Release"
|
||
. Fill in the release date ({{ release_date | formatdate }})
|
||
. It will give the option of transitioning issues marked fix-for the released version to the
|
||
next version, but do not do this as it will send an email for each issue :)
|
||
links:
|
||
- https://issues.apache.org/jira/plugins/servlet/project-config/LUCENE/versions
|
||
- !Todo
|
||
id: jira_close_resolved
|
||
title: Close all issues resolved in the release
|
||
description: |-
|
||
Go to JIRA search to find all issues that were fixed in the release
|
||
you just made, whose Status is Resolved.
|
||
|
||
. Go to https://issues.apache.org/jira/issues/?jql=project+in+(LUCENE)+AND+status=Resolved+AND+fixVersion={{ release_version }}
|
||
. Do a bulk change (Under Tools... menu) to close all of these issues. This is a workflow transition task
|
||
. In the 'Comment' box type `Closing after the {{ release_version }} release`
|
||
. *Uncheck* the box that says `Send mail for this update`
|
||
links:
|
||
- https://issues.apache.org/jira/issues/?jql=project+in+(LUCENE)+AND+status=Resolved+AND+fixVersion={{ release_version }}
|
||
- !Todo
|
||
id: jira_change_unresolved
|
||
title: Remove fixVersion for unresolved
|
||
description: |-
|
||
Do another JIRA search to find all issues with Resolution=_Unresolved_ and fixVersion=_{{ release_version }}_.
|
||
|
||
. Open https://issues.apache.org/jira/issues/?jql=project+=+LUCENE+AND+resolution=Unresolved+AND+fixVersion={{ release_version }}
|
||
. In the `Tools` menu, start a bulk change - operation="Edit issues"
|
||
. Identify issues that *are included* in the release, but are unresolved e.g. due to being REOPENED. These shall *not* be bulk changed!
|
||
. Check the box next to `Change Fix Version/s` and in the dropdown `Find and remove these`, selecting v {{ release_version }}
|
||
. On the bottom of the form, uncheck the box that says `Send mail for this update`
|
||
. Click `Next`, review the changes and click `Confirm`
|
||
links:
|
||
- https://issues.apache.org/jira/issues/?jql=project+=+LUCENE+AND+resolution=Unresolved+AND+fixVersion={{ release_version }}
|
||
- !Todo
|
||
id: new_jira_versions_bugfix
|
||
title: Add a new version in JIRA for the next release
|
||
description: |-
|
||
Go to the JIRA "Manage Versions" Administration pages and add the new version:
|
||
|
||
. Create a new (unreleased) version `{{ get_next_version }}`
|
||
types:
|
||
- bugfix
|
||
links:
|
||
- https://issues.apache.org/jira/plugins/servlet/project-config/LUCENE/versions
|
||
- !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.
|
||
|
||
Currenlty 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
|