[!NOTE] This is a project-specific procedure, based on the Apache Release Creation Process
The version number that is used in the build process is called the Package Version, which is the same version number used for the NuGet package. The assembly version, file version, and informational version are all derived from the Package Version during the build process. The Package Version uses the following rules.
Since Lucene.NET is a port of a semantically versioned component, our versioning scheme is to use the same version number as Lucene on production release (i.e. 4.8.0
). Any patches thereafter (breaking API change or not) will add a revision number (i.e 4.8.0.1
).
We are also using pre-release version numbers (i.e. 4.8.0-beta00001
) for all unstable versions up to the production release. When doing pre-releases, revision numbers are not supported.
ONLY when changes are updated from a newer Lucene version to Lucene.NET, the Lucene.NET version number is updated to match the Lucene version (i.e. 4.8.0
> 4.8.1
or 4.8.0
> 5.10.0
).
Version numbers always progress in the following order
4.8.0-beta00001
)4.8.0
)4.8.0.1
, where N is 2, 4.8.0.2
, etc)Version numbers correspond to GitHub milestones, so when releasing a milestone, the same version number should be used
For legacy reasons, tagging the Git repository to indicate a version uses a different version format, but it must include all of the elements of the Package Version, for example:
# Pre-Release
Lucene.Net_4_8_0_beta00001
# Production Release
Lucene.Net_4_8_0
# Production Release Patch (breaking API changes included)
Lucene.Net_4_8_0_1
Nominate a release manager (must be a Lucene.NET committer)
Review all GitHub issues associated with the release milestone. All issues should be resolved or closed.
Any issues that have been assigned to the release milestone that are still in progress should be moved to the next milestone. Any critical or blocker issues should be resolved on the dev
mailing list. Discuss any issues that you are unsure of on the dev
mailing list.
The following steps need only to be performed once.
Install the Java Runtime Environment
Install a subversion command line client, such as TortoiseSVN
Install GNU Privacy Guard
Generate a code signing key if you don't already have one
Make sure you have your PGP key entered into https://id.apache.org/. Your KEYS will then be present in https://people.apache.org/keys/group/lucenenet.asc.
Make sure you have your PGP keys password.
Append your PGP key to the KEYS
file in https://dist.apache.org/repos/dist/release:
dotnet msbuild -t:AppendSignature -p:ApacheID=<apacheId>
[!NOTE] You may be prompted for your password
Prepare a GitHub Release. Review the master branch commit history, and create a new DRAFT GitHub release using the following template:
> This release contains <any important changes that users should be aware of>
## Change Log
### Breaking Changes
* #<GitHub Issue ID (optional)> - <A descriptive title (may need to add context or summarize)>
### Bugs
* #<GitHub Issue ID (optional)> - <A descriptive title (may need to add context or summarize)>
### Improvements
* #<GitHub Issue ID (optional)> - <A descriptive title (may need to add context or summarize)>
### New Features
* #<GitHub Issue ID (optional)> - <A descriptive title (may need to add context or summarize)>
Checkout the Lucene.NET master branch: git clone https://github.com/apache/lucenenet.git
Add Missing License Headers
Run Apache Release Audit Tool:
dotnet msbuild -t:AuditRelease
Review and commit the changes to your local Git clone, adding exclusions to .rat-excludes
and re-running as necessary
Push the changes to the remote lucenenet
repository (https://gitbox.apache.org/repos/asf/lucenenet.gif
)
git push <remote> master --tags
Execute a complete test locally (it can take up to an hour, but you may do the next step in parallel):
build -pv:<packageVersion> -t -mp:10
Execute a complete test on a temporary Azure DevOps organization (it can take up to an hour) (see build instructions on README.md).
Login to the Lucene.NET build pipeline on Azure DevOps
Click the Run pipeline
button
Ensure the master
branch is selected
Expand Variables
Update the PackageVersion
variable to the release version number (i.e. 4.8.0-beta00008
)
Click the back arrow to return to the main view
Click the Run
button to begin the build (it will take about an hour)
On your local Git clone, check out the SVN distribution repositories
dotnet msbuild -t:CheckoutRelease
Upon successful Azure DevOps build, download the release
build artifact, which contains the release binaries and copy both the .src.zip
and .bin.zip
files to a new folder named <repo root>/svn-dev/<packageVersion>/
On your local Git clone, tag the repository using the info in RELEASE-TODO.txt
git log
RELEASE-TODO.txt
git tag -a <tag from RELEASE-TODO.txt> -m "<tag from RELEASE-TODO.txt>"
git push <remote-name (defaults to origin)> master --tags
Sign the release
artifacts using GnuPG
dotnet msbuild -t:SignReleaseCandidate -p:PackageVersion=<packageVersion>
[!NOTE] You may be prompted for your password
Check signature of generated artifacts (the SignReleaseCandidate
target above runs the commands)
Perform basic checks against the release binary:
Check presence and appropriateness of LICENSE, NOTICE, and README files.
Check the nupkg
files to ensure they can be referenced in Visual Studio.
dev
Distribution Repository# Note the command copies the <repo root>/svn-release/KEYS file to <repo-root>/svn-dev/KEYS # and overwrites any local changes to it dotnet msbuild -t:CommitReleaseCandidate -p:PackageVersion=<packageVersion>
Notify the developer mailing list of a new version vote. Be sure to replace all values in [] with the appropriate values. Use the Countdown Timer Tool to create a timer to show exactly when the vote ends.
To: dev@lucenenet.apache.org
Message Subject: [VOTE] Apache Lucene.NET [version]
------------------------------------------------------
I have posted a new release for the Apache Lucene.NET [version] release and it is ready for testing.
The binaries can be downloaded from:
https://dist.apache.org/repos/dist/dev/lucenenet
The release was made from the Apache Lucene.NET [version] tag at:
https://github.com/apache/lucenenet/tree/[tag]
The release notes are listed at:
https://github.com/apache/lucenenet/releases/tag/[tag-url]"
The release was made using the Lucene.NET release process, documented on the website:
https://lucenenet.apache.org/release.html <!-- TODO: Update URL -->
Please vote on releasing these packages as Apache Lucene.NET [version]. The vote is open for at least the next 72 hours, i.e. midnight UTC on [YYYY-MM-DD]
http://www.timeanddate.com/counters/customcounter.html?year=[YYYY]&month=[MM]&day=[DD]
Only votes from Lucene.NET PMC are binding, but everyone is welcome to check the release candidate and vote.
The vote passes if at least three binding +1 votes are cast.
[ ] +1 Release the packages as Apache Lucene.NET [VERSION]
[ ] -1 Do not release the packages because...
[!NOTE] Only people with permissions on GitHub will be able to see the draft release notes. PMC members and committers can have permissions, but only if they set them up themselves.
The vote is successful if at least 3 +1 votes are received from Lucene.NET PMC members after a minimum of 72 hours of sending the vote email. Acknowledge the voting results on the mailing list in the VOTE thread.
To: dev@lucenenet.apache.org
Message Subject: [RESULT] [VOTE] Apache Lucene.NET [version]
------------------------------------------------------
The vote has now closed. The results are:
Binding Votes:
+1 [TOTAL BINDING +1 VOTES]
-1 [TOTAL BINDING -1 VOTES]
The vote is ***successful/not successful***
[!TIP] Due to spam issues you may want to bcc each person who voted on the RESULT email to ensure they receive it.
Login to the Lucene.NET release pipeline on Azure DevOps
Click the release that corresponds to the version that is being released
The Release [VOTE]
step should be waiting for manual intervention, click the Resume
button
Enter the result of the vote in the following format: Binding Votes +1: [3] 0: [0] -1: [0] Non Binding Votes +1: [3] 0: [0] -1: [0]
, updating the values within [ ]
appropriately
Upon clicking Resume
again the release will finish, submitting the NuGet packages to NuGet.org
Commit the distribution via SVN to https://dist.apache.org/repos/dist/release:
dotnet msbuild -t:CommitRelease -p:PackageVersion=<packageVersion>
To reduce the load on the ASF mirrors, projects are required to delete old releases (see http://www.apache.org/legal/release-policy.html#when-to-archive).
Remove the old releases from SVN under https://dist.apache.org/repos/dist/release/lucenenet/.
/websites/site/lucenetemplate/doap_Lucene_Net.rdf
file to reflect the new version and ensure other links/info in the file are correct.[!IMPORTANT] Only update the version if it's a new stable version.
/websites/site/download
, in most cases it's easiest to just copy the previous release page.uid
in the header is correct/websites/site/download/toc.yml
filedocs/[version]
, for example: docs/4.8.0-beta00008
./websites/apidocs/docfx.json
and change the globalMetadata
section:_appTitle
should be: “Apache Lucene.NET [Version] Documentation”_appFooter
has the correct copyright year_gitContribute.branch
should be the name of the branch just createdmaster
branch, or create a Pull Request to target the master
branch if you want to review changes that way or want another team member to review changes.Log the new version at https://reporter.apache.org/addrelease.html?lucenenet
Publish the Draft GitHub Release that was created earlier, updating the tag if necessary
Send announcement email
[!IMPORTANT] Only include announce@apache.org if it is a stable release version
To: announce@apache.org; dev@lucenenet.apache.org; user@lucenenet.apache.org
Message Subject: [ANNOUNCE] Apache Lucene.NET [version] Released
------------------------------------------------------
The Apache Lucene.NET team is pleased to announce the release of version [version] of Apache Lucene.NET. Apache Lucene.NET is a .NET full-text search engine framework, a C# port of the popular Apache Lucene project. Apache Lucene.NET is not a complete application, but rather a code library and API that can easily be used to add search capabilities to applications.
The Lucene.NET [version] binary and source distributions are available for download from our download page:
https://lucenenet.apache.org/download/download.html
The Lucene.NET library is distributed by NuGet.org as well. See the README.md page for more details:
https://github.com/apache/lucenenet#all-packages-1
Changes in this version:
https://github.com/apache/lucenenet/releases/tag/<tag>
The Apache Lucene.NET Team
The release vote may fail due to an issue discovered in the release candidate. If the vote fails the release should be canceled by:
A new release candidate can now be prepared. When complete, a new VOTE thread can be started as described in the steps above.