forked from apache/solr
-
Notifications
You must be signed in to change notification settings - Fork 0
/
releaseWizard.yaml
1759 lines (1660 loc) · 74.4 KB
/
releaseWizard.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#
# 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/Fingerprint. This must be
the same key ID & Fingerprint 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 }} 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: python3 -u dev-tools/scripts/addVersion.py {{ next_version }}
tee: true
- !Command
cmd: "{{ gradle_cmd }} setOfficialAntoraYaml -Prefguide.isBranchReleased=false"
tee: true
- !Command
comment: Make sure the new antora.yaml and 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: python3 -u dev-tools/scripts/addVersion.py {{ next_version }}
tee: true
- !Command
cmd: "{{ gradle_cmd }} setOfficialAntoraYaml -Prefguide.isBranchReleased=false"
tee: true
- !Command
comment: Make sure the new antora.yaml and 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: setup_gpg
title: Setup the gpg agent
depends:
- gpg
commands: !Commands
root_folder: '{{ git_checkout_folder }}'
commands_text: |-
In this step we will pre-set the passphrase so that the GPG Agent can cache it for use in the RC build.
commands:
- !Command
cmd: echo foo | gpg --detach-sign --use-agent --pinentry-mode loopback --local-user {{ gpg.gpg_fingerprint | default("<gpg_fingerprint>", True) }}
tee: false
shell: true
live: true
- !Todo
id: build_rc
title: Build the release candidate
depends:
- setup_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 }} --manifest-username {{ gpg.apache_id }} --sign {{ gpg.gpg_fingerprint | default("<gpg_fingerprint>", True) }} --gpg-pass-noprompt
comment: "Using gpg command for signing."
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