Repository: yetus Updated Branches: refs/heads/master 90cd34ec0 -> b2960a6b7
YETUS-568. break apart versioning of files and directories Signed-off-by: Sean Busbey <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/yetus/repo Commit: http://git-wip-us.apache.org/repos/asf/yetus/commit/b2960a6b Tree: http://git-wip-us.apache.org/repos/asf/yetus/tree/b2960a6b Diff: http://git-wip-us.apache.org/repos/asf/yetus/diff/b2960a6b Branch: refs/heads/master Commit: b2960a6b7cb0333e91ff628dc54bd84e75a5e96f Parents: 90cd34e Author: Allen Wittenauer <[email protected]> Authored: Wed Nov 1 08:00:48 2017 -0700 Committer: Sean Busbey <[email protected]> Committed: Wed Nov 29 11:13:33 2017 -0600 ---------------------------------------------------------------------- asf-site-src/config.rb | 6 +- asf-site-src/source/contribute/releases.md | 24 +++--- .../in-progress/releasedocmaker.md | 71 +++++++++++------ asf-site-src/source/downloads.html.md.erb | 2 +- build.sh | 6 +- release-doc-maker/releasedocmaker.py | 84 ++++++++++++++++---- 6 files changed, 132 insertions(+), 61 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/yetus/blob/b2960a6b/asf-site-src/config.rb ---------------------------------------------------------------------- diff --git a/asf-site-src/config.rb b/asf-site-src/config.rb index 8562d14..7cf2c43 100644 --- a/asf-site-src/config.rb +++ b/asf-site-src/config.rb @@ -95,14 +95,12 @@ def releasenotes(output, version) # file timestamp `(cd #{output} && #{RELEASEDOCMAKER} --project=YETUS --version=#{version} \ --projecttitle="Apache Yetus" \ + --dirversions \ --usetoday --license --lint=all)` unless $CHILD_STATUS.exitstatus == 0 abort("releasedocmaker failed to generate release notes for #{version}.") end - FileUtils.mv("#{output}/#{version}/RELEASENOTES.#{version}.md", - "#{output}/#{version}/RELEASENOTES.md") - FileUtils.mv("#{output}/#{version}/CHANGES.#{version}.md", - "#{output}/#{version}/CHANGES.md") + end GITREPO = 'https://git-wip-us.apache.org/repos/asf/yetus.git'.freeze http://git-wip-us.apache.org/repos/asf/yetus/blob/b2960a6b/asf-site-src/source/contribute/releases.md ---------------------------------------------------------------------- diff --git a/asf-site-src/source/contribute/releases.md b/asf-site-src/source/contribute/releases.md index a596abc..eb54b67 100644 --- a/asf-site-src/source/contribute/releases.md +++ b/asf-site-src/source/contribute/releases.md @@ -160,14 +160,14 @@ Depending on how candidate evaluation goes, you may end up performing these step 1. Build release artifacts. You should use our convenience script to create the tarballs and markdown documents for a release. Run the following from the release staging branch and inspect the results: $ ./build.sh --release - $ ls -lah target/RELEASENOTES.md target/CHANGES.md target/*.tar.gz + $ ls -lah target/RELEASENOTES.md target/CHANGELOG.md target/*.tar.gz 1. Check out the staging area for release candidates and make a directory for this candidate, somewhere outside of the your working directory. Copy the artifacts from the previous step into place. For example, when working on RC1 for the 0.2.0 release $ svn co https://dist.apache.org/repos/dist/dev/yetus/ yetus-dist-dev $ cd yetus-dist-dev $ mkdir 0.2.0-RC1 $ cd 0.2.0-RC1 - $ cp path/to/yetus/target/RELEASENOTES.md path/to/yetus/target/CHANGES.md path/to/yetus/target/*.tar.gz . + $ cp path/to/yetus/target/RELEASENOTES.md path/to/yetus/target/CHANGELOG.md path/to/yetus/target/*.tar.gz . 1. While still in the staging area, sign the artifacts and create the needed checksum files: $ for artifact in *; do @@ -191,7 +191,7 @@ Afterwards, the artifacts should be visible via the web under the same URL used https://dist.apache.org/repos/dist/dev/yetus/0.2.0-RC1/ As of this vote the relevant md5 hashes are: - MD5 (CHANGES.md) = b7f7894d686a59aad1a4afe2ae8fbb94 + MD5 (CHANGELOG.md) = b7f7894d686a59aad1a4afe2ae8fbb94 MD5 (RELEASENOTES.md) = e321ef2909e3e51ce40bbf701159b01e MD5 (yetus-0.2.0-bin.tar.gz) = e23fe4d34611a4c027df3f515cb46d7e MD5 (yetus-0.2.0-src.tar.gz) = e57b96533092356f3d5b9b4f47654fe9 @@ -232,10 +232,10 @@ For example, if we use the url from our exemplar VOTE email, the process would l $ wget --recursive --no-parent --quiet 'https://dist.apache.org/repos/dist/dev/yetus/0.2.0-RC1/' $ find dist.apache.org/ -type f - dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/CHANGES.md - dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/CHANGES.md.asc - dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/CHANGES.md.md5 - dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/CHANGES.md.mds + dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/CHANGELOG.md + dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/CHANGELOG.md.asc + dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/CHANGELOG.md.md5 + dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/CHANGELOG.md.mds dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/index.html dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/RELEASENOTES.md dist.apache.org//repos/dist/dev/yetus/0.2.0-RC1/RELEASENOTES.md.asc @@ -465,16 +465,16 @@ It may take up to 24 hours for the artifacts to make their way to the various mi D 0.2.0-RC1/yetus-0.2.0-src.tar.gz.md5 D 0.2.0-RC1/yetus-0.2.0-bin.tar.gz.asc D 0.2.0-RC1/RELEASENOTES.md - D 0.2.0-RC1/CHANGES.md.mds - D 0.2.0-RC1/CHANGES.md.md5 + D 0.2.0-RC1/CHANGELOG.md.mds + D 0.2.0-RC1/CHANGELOG.md.md5 D 0.2.0-RC1/yetus-0.2.0-src.tar.gz D 0.2.0-RC1/RELEASENOTES.md.asc D 0.2.0-RC1/yetus-0.2.0-bin.tar.gz.mds D 0.2.0-RC1/yetus-0.2.0-bin.tar.gz.md5 D 0.2.0-RC1/yetus-0.2.0-src.tar.gz.asc - D 0.2.0-RC1/CHANGES.md + D 0.2.0-RC1/CHANGELOG.md D 0.2.0-RC1/RELEASENOTES.md.mds - D 0.2.0-RC1/CHANGES.md.asc + D 0.2.0-RC1/CHANGELOG.md.asc D 0.2.0-RC1/RELEASENOTES.md.md5 D 0.2.0-RC1/yetus-0.2.0-bin.tar.gz D 0.2.0-RC1/yetus-0.2.0-src.tar.gz.mds @@ -593,7 +593,7 @@ You should then post this patch for review. Once you've gotten feedback, it's fi The list of changes included in this release and release notes can be browsed at: - https://yetus.apache.org/documentation/0.2.0/CHANGES/ + https://yetus.apache.org/documentation/0.2.0/CHANGELOG/ https://yetus.apache.org/documentation/0.2.0/RELEASENOTES/ Documentation for this release is at: http://git-wip-us.apache.org/repos/asf/yetus/blob/b2960a6b/asf-site-src/source/documentation/in-progress/releasedocmaker.md ---------------------------------------------------------------------- diff --git a/asf-site-src/source/documentation/in-progress/releasedocmaker.md b/asf-site-src/source/documentation/in-progress/releasedocmaker.md index a996efd..27a5d0a 100644 --- a/asf-site-src/source/documentation/in-progress/releasedocmaker.md +++ b/asf-site-src/source/documentation/in-progress/releasedocmaker.md @@ -37,7 +37,7 @@ releasedocmaker Building changelog information in a form that is human digestible but still containing as much useful information is difficult. Many attempts over the years have resulted in a variety of methods that projects use to solve this problem: * JIRA-generated release notes from the "Release Notes" button -* Manually modified CHANGES file +* Manually modified CHANGELOG file * Processing git log information All of these methods have their pros and cons. Some have issues with accuracy. Some have issues with lack of details. None of these methods seem to cover all of the needs of many projects and are full of potential pitfalls. @@ -55,28 +55,26 @@ dateutil may be installed via pip: `pip install python-dateutil` Minimally, the name of the JIRA project and a version registered in JIRA must be provided: ```bash -$ releasedocmaker.py --project (project) --version (version) +$ releasedocmaker --project (project) --version (version) ``` This will query Apache JIRA, generating two files in a directory named after the given version in an extended markdown format which can be processed by both mvn site and GitHub. -* CHANGES.(version).md +* CHANGELOG.md This is similar to the JIRA "Release Notes" button but is in tabular format and includes the priority, component, reporter, and contributor fields. It also highlights Incompatible Changes so that readers know what to look out for when upgrading. The top of the file also includes the date that the version was marked as released in JIRA. -* RELEASENOTES.(version).md +* RELEASENOTES.md -If your JIRA project supports the release note field, this will contain any JIRA mentioned in the CHANGES log that is either an incompatible change or has a release note associated with it. If your JIRA project does not support the release notes field, this will be the description field. +If your JIRA project supports the release note field, this will contain any JIRA mentioned in the CHANGELOG that is either an incompatible change or has a release note associated with it. If your JIRA project does not support the release notes field, this will be the description field. -For example, to build the release documentation for HBase v1.2.0... +For example, to build the release documentation for HBase v1.2.0: ```bash -$ releasedocmaker.py --project HBASE --version 1.2.0 +$ releasedocmaker --project HBASE --version 1.2.0 ``` -... will create a 1.2.0 directory and inside that directory will be CHANGES.1.2.0.md and RELEASENOTES.1.2.0.md . - By default, release notes are expected to be in plain text. However, you can write them in markdown if you include a header at the top of your release note: ```xml @@ -89,17 +87,44 @@ remaining text By default, it will use a header that matches the project name. But that is kind of ugly and the case may be wrong. Luckily, the title can be changed: ```bash -$ releasedocmaker.py --project HBASE --version 1.2.0 --projecttitle "Apache HBase" +$ releasedocmaker --project HBASE --version 1.2.0 --projecttitle "Apache HBase" +``` + +Now instead of "HBASE", it will use "Apache HBase" for some titles and headers. + +# Versioned Files and Directories + +It is sometimes useful to create the CHANGELOG and RELEASENOTES with versions attached. `releasedocmaker` supports both independently. + +```bash +$ releasedocmaker --project HBASE --version 1.2.0 --fileversions ``` -Now instead of "HBASE", it will use "Apache HBASE" for some titles and headers. +This command line will now create CHANGELOG.1.2.0.md and RELEASENOTES.1.2.0.md files. + + +```bash +$ releasedocmaker --project HBASE --version 1.2.0 --dirversions +``` + +This command line will now create a directory called 1.2.0 and inside will be the CHANGELOG.md and RELEASENOTES.md files. + + +Using both at the same time... + +```bash +$ releasedocmaker --project HBASE --version 1.2.0 --fileversions --dirversions +``` + +... results in 1.2.0/CHANGELOG.1.2.0.md and 1.2.0/RELEASENOTES.1.2.0.md files. + # Multiple Versions -The script can also generate multiple versions at once, by +Using either `--dirversions` or `--fileversions` or both simultaneously, `releasedocmaker` can also generate multiple versions at once ```bash -$ releasedocmaker.py --project HBASE --version 1.0.0 --version 1.2.0 +$ releasedocmaker --project HBASE --version 1.0.0 --version 1.2.0 --dirversions ``` This will create the files for versions 1.0.0 and versions 1.2.0 in their own directories. @@ -107,7 +132,7 @@ This will create the files for versions 1.0.0 and versions 1.2.0 in their own di But what if the version numbers are not known? releasedocmaker can also generate version data based upon ranges: ```bash -$ releasedocmaker.py --project HBASE --version 1.0.0 --version 1.2.0 --range +$ releasedocmaker --project HBASE --version 1.0.0 --version 1.2.0 --range --fileversions ``` In this form, releasedocmaker will query JIRA, discover all versions that alphabetically appear to be between 1.0.0 and 1.2.0, inclusive, and generate all of the relative release documents. This is especially useful when bootstrapping an existing project. @@ -119,7 +144,7 @@ For released versions, releasedocmaker will pull the date of the release from JI The --usetoday option can be used to signify that instead of using Unreleased, releasedocmaker should use today's date. ```bash -$ releasedocmaker.py --project HBASE --version 1.0.0 --usetoday +$ releasedocmaker --project HBASE --version 1.0.0 --usetoday ``` After using this option and release, don't forget to change JIRA's release date to match! @@ -133,13 +158,13 @@ Different projects may find one type of sort better than another, depending upon By default, releasedocmaker will sort the output based upon the resolution date of the issue starting with older resolutions. This is the same as giving these options: ```bash -$ releasedocmaker.py --project falcon --version 0.6 --sorttype resolutiondate --sortorder older +$ releasedocmaker --project falcon --version 0.6 --sorttype resolutiondate --sortorder older ``` The order can be reversed so that newer issues appear on top by providing the 'newer' flag: ```bash -$ releasedocmaker.py --project falcon --version 0.6 --sorttype resolutiondate --sortorder newer +$ releasedocmaker --project falcon --version 0.6 --sorttype resolutiondate --sortorder newer ``` In the case of multiple projects given on the command line, the projects will be interspersed. @@ -149,7 +174,7 @@ In the case of multiple projects given on the command line, the projects will be An alternative to the date-based sort is to sort based upon the issue id. This may be accomplished via: ```bash -$ releasedocmaker.py --project falcon --version 0.6 --sorttype issueid --sortorder asc +$ releasedocmaker --project falcon --version 0.6 --sorttype issueid --sortorder asc ``` This will now sort by the issue id, listing them in lowest to highest (or ascending) order. @@ -157,7 +182,7 @@ This will now sort by the issue id, listing them in lowest to highest (or ascend The order may be reversed to list them in highest to lowest (or descending) order by providing the appropriate flag: ```bash -$ releasedocmaker.py --project falcon --version 0.6 --sorttype issueid --sortorder desc +$ releasedocmaker --project falcon --version 0.6 --sorttype issueid --sortorder desc ``` In the case of multiple projects given on the command line, the projects will be grouped and then sorted by issue id. @@ -169,13 +194,13 @@ issue. If this field is found to be blank then it searches for the 'backward-inc default value for this label by using --incompatiblelabel option e.g. ```bash -$ releasedocmaker.py --project falcon --version 0.6 --incompatiblelabel not-compatible +$ releasedocmaker --project falcon --version 0.6 --incompatiblelabel not-compatible ``` or equivalently using the shorter -X option ```bash -$ releasedocmaker.py --project falcon --version 0.6 -X not-compatible +$ releasedocmaker --project falcon --version 0.6 -X not-compatible ``` # Lint Mode @@ -185,7 +210,7 @@ In order to ensure proper formatting while using mvn site, releasedocmaker puts In order to help release managers from having to scan through potentially large documents, releasedocmaker features a lint mode, triggered via --lint: ```bash -$ releasedocmaker.py --project HBASE --version 1.0.0 --lint +$ releasedocmaker --project HBASE --version 1.0.0 --lint ``` This will do the normal JIRA querying, looking for items it considers problematic. It will print the information to the screen and then exit with either success or failure, depending upon if any issues were discovered. @@ -203,5 +228,5 @@ For example directories with names like 0.6, 1.2.2, 1.2alpha etc. will all be li You can find the version of the releasedocmaker that you are using by giving the -V option. This may be helpful in finding documentation for the version you are using. ```bash -$ releasedocmaker.py -V +$ releasedocmaker -V ``` http://git-wip-us.apache.org/repos/asf/yetus/blob/b2960a6b/asf-site-src/source/downloads.html.md.erb ---------------------------------------------------------------------- diff --git a/asf-site-src/source/downloads.html.md.erb b/asf-site-src/source/downloads.html.md.erb index c83e409..28846d7 100644 --- a/asf-site-src/source/downloads.html.md.erb +++ b/asf-site-src/source/downloads.html.md.erb @@ -38,7 +38,7 @@ third-party repositories (e.g. Maven Central). <% data.versions.releases.reverse.each do | release | %> * <%= release %> * [Release Notes](/documentation/<%= release %>/RELEASENOTES) - * [CHANGES](/documentation/<%= release %>/CHANGES) + * [CHANGELOG](/documentation/<%= release %>/CHANGELOG) * Source : [yetus-<%= release %>-src.tar.gz](https://www.apache.org/dyn/closer.lua?path=/yetus/<%= release %>/yetus-<%= release %>-src.tar.gz) ([signature](https://www.apache.org/dist/yetus/<%= release %>/yetus-<%= release %>-src.tar.gz.asc), [hashes](https://www.apache.org/dist/yetus/<%= release %>/yetus-<%= release %>-src.tar.gz.mds)) * Binaries : [yetus-<%= release %>-bin.tar.gz](https://www.apache.org/dyn/closer.lua?path=/yetus/<%= release %>/yetus-<%= release %>-bin.tar.gz) ([signature](https://www.apache.org/dist/yetus/<%= release %>/yetus-<%= release %>-bin.tar.gz.asc), [hashes](https://www.apache.org/dist/yetus/<%= release %>/yetus-<%= release %>-bin.tar.gz.mds)) <% end http://git-wip-us.apache.org/repos/asf/yetus/blob/b2960a6b/build.sh ---------------------------------------------------------------------- diff --git a/build.sh b/build.sh index 6783596..6307ce9 100755 --- a/build.sh +++ b/build.sh @@ -101,8 +101,6 @@ if [ "${offline}" != "true" ]; then release-doc-maker/releasedocmaker.py --lint=all --license --outputdir target \ --project YETUS "--version=${JIRA_VERSION}" \ --projecttitle="Apache Yetus" --usetoday - mv "target/${JIRA_VERSION}/RELEASENOTES.${JIRA_VERSION}.md" target/RELEASENOTES.md - mv "target/${JIRA_VERSION}/CHANGES.${JIRA_VERSION}.md" target/CHANGES.md else echo "in offline mode, skipping release notes." fi @@ -127,7 +125,7 @@ if [ "${release}" = "true" ]; then fi echo "creating source tarball at '$(pwd)/target/'" rm "target/yetus-${YETUS_VERSION}-src".tar* 2>/dev/null || true - pax -w -f "target/yetus-${YETUS_VERSION}-src.tar" -s "/target/yetus-${YETUS_VERSION}/" target/RELEASENOTES.md target/CHANGES.md + pax -w -f "target/yetus-${YETUS_VERSION}-src.tar" -s "/target/yetus-${YETUS_VERSION}/" target/RELEASENOTES.md target/CHANGELOG.md current=$(basename "$(pwd)") #shellcheck disable=SC2038 (cd ..; find "${current}" \( -name target -o -name publish -o -name .git \) -prune -o ! -type d -print | xargs pax -w -a -f "${current}/target/yetus-${YETUS_VERSION}-src.tar" -s "/${current}/yetus-${YETUS_VERSION}/") @@ -159,7 +157,7 @@ for i in LICENSE NOTICE; do fi done -cp target/RELEASENOTES.md target/CHANGES.md "${bin_tarball}" +cp target/RELEASENOTES.md target/CHANGELOG.md "${bin_tarball}" cp -r asf-site-src/publish/documentation/in-progress "${bin_tarball}/docs" mkdir -p "${bin_tarball}/lib" http://git-wip-us.apache.org/repos/asf/yetus/blob/b2960a6b/release-doc-maker/releasedocmaker.py ---------------------------------------------------------------------- diff --git a/release-doc-maker/releasedocmaker.py b/release-doc-maker/releasedocmaker.py index 080abf1..c9c2eca 100755 --- a/release-doc-maker/releasedocmaker.py +++ b/release-doc-maker/releasedocmaker.py @@ -542,8 +542,18 @@ def parse_args(): parser = OptionParser( usage=usage, epilog= - "Markdown-formatted CHANGES and RELEASENOTES files will be stored" + "Markdown-formatted CHANGELOG and RELEASENOTES files will be stored" " in a directory named after the highest version provided.") + parser.add_option("--dirversions", + dest="versiondirs", + action="store_true", + default=False, + help="Put files in versioned directories") + parser.add_option("--fileversions", + dest="versionfiles", + action="store_true", + default=False, + help="Write files with embedded versions") parser.add_option("-i", "--index", dest="index", @@ -647,6 +657,14 @@ def parse_args(): (options, _) = parser.parse_args() + # Handle the version string right away and exit + if options.release_version: + with open( + os.path.join( + os.path.dirname(__file__), "../VERSION"), 'r') as ver_file: + print ver_file.read() + sys.exit(0) + # Validate options if not options.release_version: if options.versions is None: @@ -664,17 +682,15 @@ def parse_args(): else: options.output_directory = options.output_directory[0] + if options.range or len(options.versions) > 1: + if not options.versiondirs and not options.versionfiles: + parser.error("Multiple versions require either --fileversions or --dirversions") + return options def main(): options = parse_args() - if options.release_version: - with open( - os.path.join( - os.path.dirname(__file__), "../VERSION"), 'r') as ver_file: - print ver_file.read() - sys.exit(0) if options.output_directory is not None: # Create the output directory if it does not exist. @@ -743,16 +759,50 @@ def main(): if not os.path.exists(vstr): os.mkdir(vstr) - reloutputs = Outputs("%(ver)s/RELEASENOTES.%(ver)s.md", - "%(ver)s/RELEASENOTES.%(key)s.%(ver)s.md", [], - {"ver": version, - "date": reldate, - "title": title}) - choutputs = Outputs("%(ver)s/CHANGES.%(ver)s.md", - "%(ver)s/CHANGES.%(key)s.%(ver)s.md", [], - {"ver": version, - "date": reldate, - "title": title}) + if options.versionfiles and options.versiondirs: + reloutputs = Outputs("%(ver)s/RELEASENOTES.%(ver)s.md", + "%(ver)s/RELEASENOTES.%(key)s.%(ver)s.md", [], + {"ver": version, + "date": reldate, + "title": title}) + choutputs = Outputs("%(ver)s/CHANGELOG.%(ver)s.md", + "%(ver)s/CHANGELOG.%(key)s.%(ver)s.md", [], + {"ver": version, + "date": reldate, + "title": title}) + elif options.versiondirs: + reloutputs = Outputs("%(ver)s/RELEASENOTES.md", + "%(ver)s/RELEASENOTES.%(key)s.md", [], + {"ver": version, + "date": reldate, + "title": title}) + choutputs = Outputs("%(ver)s/CHANGELOG.md", + "%(ver)s/CHANGELOG.%(key)s.md", [], + {"ver": version, + "date": reldate, + "title": title}) + elif options.versionfiles: + reloutputs = Outputs("RELEASENOTES.%(ver)s.md", + "RELEASENOTES.%(key)s.%(ver)s.md", [], + {"ver": version, + "date": reldate, + "title": title}) + choutputs = Outputs("CHANGELOG.%(ver)s.md", + "CHANGELOG.%(key)s.%(ver)s.md", [], + {"ver": version, + "date": reldate, + "title": title}) + else: + reloutputs = Outputs("RELEASENOTES.md", + "RELEASENOTES.%(key)s.md", [], + {"ver": version, + "date": reldate, + "title": title}) + choutputs = Outputs("CHANGELOG.md", + "CHANGELOG.%(key)s.md", [], + {"ver": version, + "date": reldate, + "title": title}) if options.license is True: reloutputs.write_all(ASF_LICENSE)
