| # |
| # 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 Solr, 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 Solr 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@solr.apache.org |
| Subject: [{% if passed %}RESULT{% else %}FAILED{% endif %}] [VOTE] Release Solr {{ 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_solr: | |
| Title: Apache Solr™ {{ release_version }} available |
| category: solr/news |
| save_as: |
| |
| The Solr PMC is pleased to announce the release of Apache Solr {{ release_version }}. |
| |
| Solr is the popular, blazing fast, open source NoSQL search platform from the Apache Solr project. Its major features include powerful full-text search, hit highlighting, faceted search, dynamic clustering, database integration, rich document handling, and geospatial search. Solr is highly scalable, providing fault tolerant distributed search and indexing, and powers the search and navigation features of many of the world's largest internet sites. |
| |
| Solr {{ release_version }} is available for immediate download at: |
| |
| <https://solr.apache.org/downloads.html> |
| |
| ### Solr {{ release_version }} Release Highlights: |
| |
| * Feature 1 pasted from WIKI release notes |
| * Feature 2 ... |
| |
| Please refer to the Upgrade Notes in the Solr Ref Guide for information on upgrading from previous Solr versions: |
| |
| <https://solr.apache.org/guide/solr/{{ release_version_refguide }}/upgrade-notes/solr-upgrade-notes.html> |
| |
| Please read CHANGES.txt for a full list of {% if is_feature_release %}new features, changes and {% endif %}bugfixes: |
| |
| <https://solr.apache.org/{{ release_version_underscore }}/changes/Changes.html> |
| announce_solr_mail: | |
| The template below can be used to announce the Solr release to the |
| internal mailing lists. |
| |
| .Mail template |
| ---- |
| To: dev@solr.apache.org, users@solr.apache.org |
| Subject: [ANNOUNCE] Apache Solr {{ release_version }} released |
| |
| (( template=announce_solr_mail_body )) |
| ---- |
| announce_solr_sign_mail: | |
| The template below can be used to announce the Solr 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 Solr {{ release_version }} released |
| |
| (( template=announce_solr_mail_body )) |
| ---- |
| announce_solr_mail_body: | |
| {% for line in load_lines(solr_news_file, 4) -%} |
| {{ 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 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 Solr |
| 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/solr/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/solr/KEYS |
| - https://github.com/apache/solr/blob/main/help/publishing.txt |
| - !Todo |
| id: jira_permissions |
| title: Obtain the necessary 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/SOLR |
| - !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: fix_build_failures |
| title: Look into common build failures |
| description: | |
| Look over recent build results sent to the builds@solr.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@solr.apache.org. |
| You can also find failure statistics at http://fucit.org/solr-jenkins-reports/ |
| - !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/solr.git solr |
| 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 --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: update_minor_branch_prerelease_antora |
| title: Update Ref Guide Metadata for new Minor Branch |
| description: | |
| This will update the "solr/solr-ref-guide/antora.yml" file. |
| |
| The file shouldn't change much, but it should pick up new dependency versions, if they have changed. |
| types: |
| - major |
| - minor |
| depends: create_minor_branch |
| commands: !Commands |
| root_folder: '{{ git_checkout_folder }}' |
| commands_text: Run these commands to update the antora.yml |
| commands: |
| - !Command |
| cmd: git checkout {{ release_branch }} |
| tee: true |
| - !Command |
| cmd: git pull --ff-only |
| tee: true |
| - !Command |
| cmd: "{{ gradle_cmd }} setOfficialAntoraYaml -Prefguide.isBranchReleased=false" |
| tee: true |
| - !Command |
| cmd: git add solr/solr-ref-guide/antora.yml && git commit -m "Update Antora metadata for pre-released minor version {{ release_version }}" && git push |
| 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: "{{ gradle_cmd }} setOfficialAntoraYaml -Prefguide.isBranchReleased=false" |
| 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. |
| - !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: "{{ gradle_cmd }} setOfficialAntoraYaml -Prefguide.isBranchReleased=false" |
| 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 |
| - !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@solr.apache.org |
| Subject: New branch and feature freeze for Solr {{ 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@solr.apache.org |
| Subject: Bugfix release Solr {{ 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/SOLR/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/SOLR/versions |
| - !Todo |
| id: jira_blocker_refguide |
| title: Add a blocker JIRA for RefGuide |
| description: |- |
| To make sure a new release is not announced before the reference guide is complete, add a new |
| Blocker JIRA issue for version {{ release_version }} with subject |
| "Complete Major changes and Upgrade Notes in RefGudie for {{ release_version }}". |
| Note that this does not block the RC and voting process, but will block announcing the release. |
| types: |
| - major |
| - minor |
| links: |
| - https://issues.apache.org/jira/browse/SOLR |
| - !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: 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 Solr 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.gpg_fingerprint | default("<gpg_fingerprint>", 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: solr-{{ 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: solr-{{ 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 "Solr {{ 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: solr-{{ 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@solr.apache.org |
| Subject: [VOTE] Release Solr {{ release_version }} RC{{ rc_number }} |
| |
| Please vote for release candidate {{ rc_number }} for Solr {{ release_version }} |
| |
| The artifacts can be downloaded from: |
| {{ release_candidate_location }} |
| |
| You can run the smoke tester directly with this command: |
| |
| python3 -u dev-tools/scripts/smokeTestRelease.py \ |
| {{ release_candidate_location }} |
| |
| You can build a release-candidate of the official docker image using the following command: |
| |
| DIST_BASE={{ dist_url_base }} && \ |
| RC_FOLDER={{ release_candidate_rc_folder }} && \ |
| docker build $DIST_BASE/$RC_FOLDER/solr/docker/Dockerfile.official \ |
| --build-arg SOLR_DOWNLOAD_URL=$DIST_BASE/$RC_FOLDER/solr/solr-{{ release_version }}.tgz \ |
| -t solr-rc:{{ release_version }}-{{ rc_number }} |
| |
| 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 }}' |
| release_candidate_rc_folder: 'solr-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }}' |
| release_candidate_location: '{{ dist_url_base }}/{{ release_candidate_rc_folder }}' |
| 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/solr/{{ release_version }} -m "Solr {{ release_version }} release" {{ build_rc.git_rev | default("<git_rev>", True) }} |
| logfile: git_tag.log |
| tee: true |
| - !Command |
| cmd: git push origin releases/solr/{{ release_version }} |
| logfile: git_push_tag.log |
| tee: true |
| - !Todo |
| id: rm_staged_mvn |
| title: Delete mvn and docker artifacts from staging repo |
| vars: |
| dist_folder: solr-{{ 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 and docker artifacts so they do not end up in the Distribution Directory |
| commands: |
| - !Command |
| cmd: svn rm -m "Delete the solr maven and docker artifacts" {{ dist_stage_url }}/solr/maven {{ dist_stage_url }}/solr/docker |
| logfile: svn_rm_mvn_solr.log |
| tee: true |
| - !Todo |
| id: mv_to_release |
| title: Move release artifacts to release repo |
| depends: rm_staged_mvn |
| vars: |
| dist_folder: solr-{{ 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/solr |
| 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 Solr {{ release_version }} RC{{ rc_number }} to release repo" {{ dist_stage_url }}/solr {{ dist_release_url }}/solr/{{ release_version }} |
| logfile: svn_mv_solr.log |
| tee: true |
| - !Command |
| cmd: svn rm -m "Clean up the RC folder for {{ release_version }} RC{{ rc_number }}" {{ dist_url_base }}/solr-{{ 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 |
| - !Todo |
| id: docker-publish |
| title: Publish the Official Solr Dockerfile |
| depends: mv_to_release |
| description: | |
| For every release, we publish the official dockerfile for solr via the methods required by Docker. |
| |
| This will start the process, and will ultimately create a PR in https://github.com/docker-library/official-images. |
| This PR creation is automated, you do not need to do more work beyond these steps. |
| |
| When that PR is approved and merged, the Official image for this Solr version will be built and available for use. |
| vars: |
| docker_version: '{{ release_version_major }}.{{ release_version_minor }}' |
| dist_folder: solr-{{ release_version }}-RC{{ rc_number }}-rev-{{ build_rc.git_rev | default("<git_rev>", True) }} |
| commands: !Commands |
| root_folder: '{{ release_folder }}' |
| commands_text: Make sure that each command is successful. This is very imperative. |
| confirm_each_command: true |
| remove_files: |
| - '{{ git_solr_docker_folder }}' |
| commands: |
| - !Command |
| cmd: git clone --progress https://gitbox.apache.org/repos/asf/solr-docker.git solr-docker |
| comment: Run this command to clone the solr-docker git repo |
| logfile: solr_docker_git_clone.log |
| - !Command |
| cmd: git checkout main && git pull --ff-only |
| cwd: solr-docker |
| comment: Checkout the most recent main version |
| logfile: solr_docker_git_checkout.log |
| - !Command |
| cmd: "mkdir -p {{ docker_version }} && cp {{ [dist_file_path, dist_folder, 'solr', 'docker', 'Dockerfile.official'] | path_join }} {{ docker_version }}/Dockerfile" |
| cwd: solr-docker |
| comment: Add the new Dockerfile to the repo |
| logfile: solr_docker_add_dockerfile.log |
| - !Command |
| cmd: 'git add {{ docker_version }}/Dockerfile && git commit -m "Apache Solr release {{ release_version }}"' |
| cwd: solr-docker |
| comment: Commit the new Dockerfile |
| logfile: solr_docker_commit.log |
| - !Command |
| cmd: git show HEAD |
| cwd: solr-docker |
| comment: Check that the commit look correct. Only one Dockerfile should be added or updated. |
| logfile: solr_docker_check_commit.log |
| tee: true |
| - !Command |
| cmd: git push |
| cwd: solr-docker |
| comment: Push the commit |
| logfile: solr_docker_git_push.log |
| tee: true |
| - !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: solr-{{ 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: bash dev-tools/scripts/upload-maven.sh -u {{ gpg.apache_id }} -v {{ release_version }} -c {{ git_sha }} -d "{{ [dist_file_path, dist_folder, 'solr', 'maven'] | path_join }}" |
| tee: true |
| logfile: publish_solr_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 Solr artifacts |
| . 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 Solr artifacts, "Apache Solr {{ release_version }} (commit {{ git_sha }})" |
| . Click on the "Release" button above the repository list, then enter a description when prompted, e.g. "Solr {{ 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/solr/{{ release_version }}/solr-{{ release_version }}-src.tgz.asc |
| to validate ASF repo, and https://repo1.maven.org/maven2/org/apache/solr/solr-core/{{ release_version }}/solr-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/solr-site |
| but the Javadocs and Solr Reference Guide 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 link below shall work. |
| links: |
| - https://solr.apache.org/docs/{{ version }} |
| vars: |
| release_tag: releases/solr/{{ 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 Solr {{ release_version }}" import {{ git_checkout_folder }}/solr/documentation/build/site https://svn.apache.org/repos/infra/sites/solr/docs/{{ version }} |
| logfile: add-docs-solr.log |
| comment: Add docs for Solr |
| - !Todo |
| id: update_minor_branch_release_antora |
| title: Update Ref Guide Metadata for release |
| description: | |
| The Solr minor branches do not contain up-to-date ref-guide metadata (antora.yml). |
| Instead, they have the information from the last release. |
| This allows us to build the official documentation from these minor branches, instead of from the release tags. |
| |
| This means that we can make fixes to older ref-guides without requiring a new release for those versions. |
| depends: tag_release |
| commands: !Commands |
| root_folder: '{{ git_checkout_folder }}' |
| commands_text: Run these commands to update the ref-guide antora metadata for the released version {{ release_version }} |
| commands: |
| - !Command |
| cmd: git checkout releases/solr/{{ release_version }} |
| tee: true |
| - !Command |
| cmd: git clean -df && git checkout -- . |
| comment: Make sure checkout is clean and up to date |
| logfile: git_clean.log |
| - !Command |
| cmd: "{{ gradle_cmd }} setOfficialAntoraYaml -Prefguide.isBranchReleased=true" |
| tee: true |
| - !Command |
| cmd: git stash |
| tee: true |
| - !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: git stash pop |
| tee: true |
| - !Command |
| cmd: git add solr/solr-ref-guide/antora.yml && git commit -m "Update Antora metadata for released minor version {{ release_version }}" && git push |
| tee: true |
| - !Todo |
| id: check_ref_guide_complete |
| title: Check that the reference guide is ready |
| types: |
| - major |
| - minor |
| description: | |
| Ensure that the reference Guide is updated for {{ release_version }}. In particular, the sections "Solr Upgrade Notes" |
| and (if applicable) also the "Major changes in Solr ..." section must be up to date for the latest release. |
| Check that the the Blocker JIRA issue created in the beginning of the release process is resolved. |
| - !Todo |
| id: build_ref_guide_htaccess |
| title: Build the ref guide .htaccess file |
| depends: update_minor_branch_release_antora |
| vars: |
| antora_htaccess_file: "{{ [rc_folder, 'antora.htaccess'] | path_join }}" |
| persist_vars: |
| - 'antora_htaccess_file' |
| commands: !Commands |
| root_folder: '{{ git_checkout_folder }}' |
| commands_text: Build the official Solr Ref Guide and store the generated .htaccess file |
| remove_files: |
| - '{{ antora_htaccess_file }}' |
| commands: |
| - !Command |
| cmd: git checkout main |
| tee: true |
| - !Command |
| cmd: git clean -df && git checkout -- . |
| comment: Make sure checkout is clean and up to date |
| logfile: git_clean.log |
| - !Command |
| cmd: git pull --ff-only |
| tee: true |
| - !Command |
| cmd: "{{ gradle_cmd }} solr:solr-ref-guide:clean" |
| comment: Clean the Ref Guide build |
| - !Command |
| cmd: "{{ gradle_cmd }} solr:solr-ref-guide:buildOfficialSite -Prefguide.official.includePrereleaseVersions=false" |
| comment: Build Official Ref Guide Site |
| - !Command |
| cmd: cp solr/solr-ref-guide/build/site/.htaccess "{{ antora_htaccess_file }}" |
| comment: Store copy of the official Ref Guide .htaccess file |
| - !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/solr-site.git solr-site |
| logfile: website_git_clone.log |
| - !Todo |
| id: website_update_versions |
| title: Update website versions |
| depends: website_git_clone |
| vars: |
| release_tag: releases/solr/{{ 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 `SOLR_LATEST_RELEASE` and `SOLR_LATEST_RELEASE_DATE` |
| variables. |
| If you relese a bugfix release for previous version, then change the `SOLR_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: website_update_antora_htaccess |
| title: Update website ref-guide htaccess |
| depends: |
| - website_update_versions |
| - build_ref_guide_htaccess |
| vars: |
| release_tag: releases/solr/{{ release_version }} |
| antora_htaccess_location: themes/solr/templates/htaccess.ref-guide-antora |
| description: | |
| We need to update the website so that the redirects generated by antora (for the ref-guide) are respected in solr.apache.org. |
| |
| Fortunately the only thing you need to change is the `htaccess.ref-guide-antora` file, and the build will do the rest. |
| commands: !Commands |
| root_folder: '{{ git_website_folder }}' |
| commands_text: Change the ref-guide-antora htaccess |
| commands: |
| - !Command |
| cmd: cp "{{ build_ref_guide_htaccess.antora_htaccess_file }}" "{{ antora_htaccess_location }}" |
| comment: Copy the ref-guide-antora htaccess |
| stdout: true |
| - !Command |
| cmd: git commit -am "Update the htaccess.ref-guide-antora for release {{ release_version }}" |
| logfile: ref-guide-antora.log |
| stdout: true |
| post_description: | |
| You will push and verify all changes in a later step |
| - !Todo |
| id: prepare_announce_solr |
| title: Author the Solr release news |
| depends: website_update_antora_htaccess |
| description: | |
| Edit a news text for the Solr 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_solr |
| commands: !Commands |
| root_folder: '{{ git_website_folder }}' |
| commands_text: | |
| Copy the Solr announcement from https://cwiki.apache.org/confluence/display/SOLR/Release+Notes |
| You have to exit the editor after edit to continue. |
| commands: |
| - !Command |
| cmd: "{{ editor }} {{ solr_news_file }}" |
| comment: Edit the Solr announcement news |
| stdout: true |
| - !Command |
| cmd: git add . && git commit -m "Adding Solr 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: prepare_announce_solr |
| 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: |
| - update_other |
| 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://solr.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://solr.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://solr.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://solr.apache.org that the site is OK. |
| |
| You can now also verify that https://solr.apache.org/api/solr-core/ redirects to the latest version |
| links: |
| - https://ci2.apache.org/#/builders/3 |
| - https://solr.apache.org |
| - https://solr.apache.org/api/solr-core/ |
| - !Todo |
| id: update_doap |
| title: Update the DOAP file |
| description: | |
| Update the Solr 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 Solr 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/solr.rdf" |
| comment: Edit Solr DOAP, add version {{ release_version }} |
| stdout: true |
| - !Command |
| cmd: git add dev-tools/doap/solr.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_solr |
| title: Announce the Solr release (@s.a.o) |
| description: | |
| (( template=announce_solr_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 solr_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_solr_sig |
| title: Announce the Solr release (announce@a.o) |
| description: | |
| (( template=announce_solr_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_Solr |
| - !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 Solr. |
| 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 Solr PMC. |
| Just use the version of this release: {{ release_version }} |
| links: |
| - https://reporter.apache.org/addrelease.html?solr |
| - !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 }} solr/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 }} solr/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 }} solr/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: 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/SOLR/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+(SOLR)+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+(SOLR)+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+=+SOLR+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+=+SOLR+AND+resolution=Unresolved+AND+fixVersion={{ release_version }} |
| - !Todo |
| id: jira_clear_security |
| title: Clear Security Level of Public Solr JIRA Issues |
| description: |- |
| ASF JIRA has a deficiency in which issues that have a security level of "Public" are nonetheless not searchable. |
| As a maintenance task, we'll clear the security flag for all public Solr JIRAs, even if it is not a task directly |
| related to the release: |
| |
| . Open in browser: https://issues.apache.org/jira/issues/?jql=project+=+SOLR+AND+level+=+%22Public%22 |
| . In the `Tools` menu, start a bulk change, select all issues and click `Next` |
| . Select operation="Edit issues" and click `Next` |
| . Click the checkbox next to `Change security level` and choose `None` in the dropdown. |
| . 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+=+SOLR+AND+level+=+%22Public%22 |
| - !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/SOLR/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 Solr PMC |
| svnpubsub area `dist/releases/solr/`. 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. |
| Note, as long as we have some releases (7.x, 8.x) in Lucene dist repo and other |
| releases (9.0 ->) in the Solr dist repo, we may need to delete two places. |
| |
| WARNING: Validate that the proposal is correct! |
| commands: |
| - !Command |
| cmd: | |
| svn rm -m "Stop publishing old Solr releases"{% for ver in mirrored_versions_to_delete %} https://dist.apache.org/repos/dist/release/lucene/solr/{{ ver }}{% endfor %} |
| logfile: svn-rm-solr.log |
| comment: Delete from Lucene dist area |
| - !Command |
| cmd: | |
| svn rm -m "Stop publishing old Solr releases"{% for ver in mirrored_versions_to_delete %} https://dist.apache.org/repos/dist/release/solr/{{ ver }}{% endfor %} |
| logfile: svn-rm-solr.log |
| comment: Delete from new Solr dist area |
