[pstl] Setup the _PSTL_VERSION macro like _LIBCPP_VERSION, and add release notes

[ldionne]

pstl/docs/ReleaseNotes.rst

9 ↗

(On Diff #194324)

This doesn't exist yet.

[MikeDvorskiy]

I don't see any "bookmarks" (technical, and others) on scheme versioning on our side.
So, I've no objections against the proposed approach.

[ldionne]

In D60464#1462398, @MikeDvorskiy wrote:

I don't see any "bookmarks" (technical, and others) on scheme versioning on our side.
So, I've no objections against the proposed approach.

Great! Note: when you're OK with a patch, you can use "Accept Revision" in Phabricator so that Phabricator won't complain when I push the patch. I'll accept my own patch for now :)

[MikeDvorskiy]

pstl/trunk/test/pstl/version.pass.cpp

17

lost

return 0;

?

[ldionne]

It's implicit in C++. I mean we can decide to do it like the rest of libc++, but we don't have to. For libc++, the reasoning is that it's needed to test in a freestanding environment.

@rodgert @MikeDvorskiy Do you guys want to consistently use return 0; at the end of main? If so, I'll fix this (and any other test that doesn't do it).

[rodgert]

In D60464#1464545, @ldionne wrote:

It's implicit in C++. I mean we can decide to do it like the rest of libc++, but we don't have to. For libc++, the reasoning is that it's needed to test in a freestanding environment.

@rodgert @MikeDvorskiy Do you guys want to consistently use return 0; at the end of main? If so, I'll fix this (and any other test that doesn't do it).

I do it out of habit (because I'm old and wrote C before C++ was really a thing you could use seriously) but I don't have a strong opinion either way on this.

[ldionne]

In D60464#1464656, @rodgert wrote:

In D60464#1464545, @ldionne wrote:

It's implicit in C++. I mean we can decide to do it like the rest of libc++, but we don't have to. For libc++, the reasoning is that it's needed to test in a freestanding environment.

@rodgert @MikeDvorskiy Do you guys want to consistently use return 0; at the end of main? If so, I'll fix this (and any other test that doesn't do it).

I do it out of habit (because I'm old and wrote C before C++ was really a thing you could use seriously) but I don't have a strong opinion either way on this.

Done in r358302.

[MikeDvorskiy]

// The version is XYYZ, where X is major, YY is minor, and Z is patch (i.e. X.YY.Z)

What does a "patch" mean?
May we increment(and rely on) _PSTL_VERSION_PATCH any time when we submitted something fixes or new features?

[ldionne]

In D60464#1466924, @MikeDvorskiy wrote:

// The version is XYYZ, where X is major, YY is minor, and Z is patch (i.e. X.YY.Z)

What does a "patch" mean?
May we increment(and rely on) _PSTL_VERSION_PATCH any time when we submitted something fixes or new features?

The way I see this used in LLVM is for point releases, e.g. LLVM 7.0.1 (see http://releases.llvm.org). We don't seem to be using the MINOR version anymore though.

[MikeDvorskiy]

In that case, may we "reserve" MINOR version to differ PSTL code version?

[ldionne]

In D60464#1466986, @MikeDvorskiy wrote:

In that case, may we "reserve" MINOR version to differ PSTL code version?

I'm not sure I understand what you mean. You mean tracking individual commits using the minor version?

[akukanov]

In D60464#1466986, @MikeDvorskiy wrote:

In that case, may we "reserve" MINOR version to differ PSTL code version?

I think we first need to understand/agree whether we want to have milestones/releases that do not follow the LLVM release cadence while deserving separate versioning. According to the discussion at our last meeting, the answer tends to be "no" - in which case, I think we should keep full correspondence between the upstream PSTL version and the LLVM version.

At Intel, we will need to decide how to combine the upstream versioning with our own one. We have higher release cadence, but also smaller functionality increments. I think that we sometimes will be ahead of the upstream on functionality. I guess we will need a separate version macro; the relations with the upstream version, if any, will need to be clearly defined and documented.

pstl/trunk/CMakeLists.txt

 #===-- CMakeLists.txt ----------------------------------------------------===##
 #
 # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 # See https://llvm.org/LICENSE.txt for license information.
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===----------------------------------------------------------------------===##
 cmake_minimum_required(VERSION 3.4.3)
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
 set(PARALLELSTL_VERSION_FILE "${CMAKE_CURRENT_SOURCE_DIR}/include/pstl/internal/pstl_config.h")
-file(STRINGS "${PARALLELSTL_VERSION_FILE}" PARALLELSTL_VERSION_SOURCE REGEX "#define PSTL_VERSION .*$")
-string(REGEX REPLACE "#define PSTL_VERSION (.*)$" "\\1" PARALLELSTL_VERSION_SOURCE "${PARALLELSTL_VERSION_SOURCE}")
-math(EXPR VERSION_MAJOR "${PARALLELSTL_VERSION_SOURCE} / 100")
-math(EXPR VERSION_MINOR "${PARALLELSTL_VERSION_SOURCE} % 100")
+file(STRINGS "${PARALLELSTL_VERSION_FILE}" PARALLELSTL_VERSION_SOURCE REGEX "#define _PSTL_VERSION .*$")
+string(REGEX REPLACE "#define _PSTL_VERSION (.*)$" "\\1" PARALLELSTL_VERSION_SOURCE "${PARALLELSTL_VERSION_SOURCE}")
+math(EXPR VERSION_MAJOR "(${PARALLELSTL_VERSION_SOURCE} / 1000)")
+math(EXPR VERSION_MINOR "((${PARALLELSTL_VERSION_SOURCE} % 1000) / 10)")
+math(EXPR VERSION_PATCH "(${PARALLELSTL_VERSION_SOURCE} % 10)")
 
-project(ParallelSTL VERSION ${VERSION_MAJOR}.${VERSION_MINOR} LANGUAGES CXX)
+project(ParallelSTL VERSION ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH} LANGUAGES CXX)
 
 option(PARALLELSTL_USE_PARALLEL_POLICIES "Enable parallel policies" OFF)
 set(PARALLELSTL_BACKEND "tbb" CACHE STRING "Threading backend; defaults to TBB")
 
 if (NOT TBB_DIR)
     get_filename_component(PSTL_DIR_NAME ${CMAKE_CURRENT_SOURCE_DIR} NAME)
     string(REPLACE pstl tbb TBB_DIR_NAME ${PSTL_DIR_NAME})
     if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/../${TBB_DIR_NAME}/cmake")

pstl/trunk/docs/ReleaseNotes.rst

+========================================
+PSTL 9.0.0 (In-Progress) Release Notes
+========================================
+
+.. contents::
+   :local:
+   :depth: 2
+
+Written by the `PSTL Team <https://pstl.llvm.org>`_
+
+.. warning::
+
+   These are in-progress notes for the upcoming pstl 9 release.
+   Release notes for previous releases can be found on
+   `the Download Page <https://releases.llvm.org/download.html>`_.
+
+Introduction
+============
+
+This document contains the release notes for the PSTL parallel algorithms
+library, part of the LLVM Compiler Infrastructure, release 9.0.0. Here we
+describe the status of the library in some detail, including major improvements
+from the previous release and new feature work. For the general LLVM release
+notes, see `the LLVM documentation <https://llvm.org/docs/ReleaseNotes.html>`_.
+All LLVM releases may be downloaded from the `LLVM releases web site
+<https://llvm.org/releases/>`_.
+
+Note that if you are reading this file from a source checkout or the main PSTL
+web page, this document applies to the *next* release, not the current one.
+To see the release notes for a specific release, please see the `releases
+page <https://llvm.org/releases/>`_.
+
+What's New in PSTL 9.0.0?
+=========================
+
+New Features
+------------
+
+API Changes
+-----------

pstl/trunk/include/pstl/internal/pstl_config.h

 // -*- C++ -*-
 //===-- pstl_config.h -----------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _PSTL_CONFIG_H
 #define _PSTL_CONFIG_H
 
-#define PSTL_VERSION 203
-#define PSTL_VERSION_MAJOR (PSTL_VERSION / 100)
-#define PSTL_VERSION_MINOR (PSTL_VERSION - PSTL_VERSION_MAJOR * 100)
+// The version is XYYZ, where X is major, YY is minor, and Z is patch (i.e. X.YY.Z)
+#define _PSTL_VERSION 9000
+#define _PSTL_VERSION_MAJOR (_PSTL_VERSION / 1000)
+#define _PSTL_VERSION_MINOR ((_PSTL_VERSION % 1000) / 10)
+#define _PSTL_VERSION_PATCH (_PSTL_VERSION % 10)
 
 // Check the user-defined macro for parallel policies
 #if defined(PSTL_USE_PARALLEL_POLICIES)
 #    undef _PSTL_USE_PAR_POLICIES
 #    define _PSTL_USE_PAR_POLICIES PSTL_USE_PARALLEL_POLICIES
 // Check the internal macro for parallel policies
 #elif !defined(_PSTL_USE_PAR_POLICIES)
 #    define _PSTL_USE_PAR_POLICIES 1

pstl/trunk/test/pstl/version.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include <pstl/internal/pstl_config.h>
+
+
+static_assert(_PSTL_VERSION == 9000);
+static_assert(_PSTL_VERSION_MAJOR == 9);
+static_assert(_PSTL_VERSION_MINOR == 00);
+static_assert(_PSTL_VERSION_PATCH == 0);
+
+int main() { }