Merge pull request #545 from vrurg/problem_solving_31

Changed release guide to reflect the latest state of things.

Author: vrurg

VERSION

@@ -3,4 +3,4 @@
 #
 # Some implementations use this file to select which test files to run, e.g.:
 # https://github.com/rakudo/rakudo/blob/master/docs/roast-spectest.data-versioning.md
-6.e-proposals
+6.e.PREVIEW

docs/announce/6.e.md

@@ -0,0 +1,70 @@
+
+# Announce: Perl 6.e Language Specification Release
+
+_This to be filled up upon actual release_
+
+## Authors
+
+The following people contributed to this version of the language,
+including making documentation updates and contributing work to known
+open‑source compiler implementations. The list is ordered alphabetically.
+
+If you believe your name has been erroneously omited, please contact us
+(https://perl6.org/irc), and we'll update the primary copy of this list.
+
+_This to be filled up upon actual release_
+
+## Changelog
+
+This document lists changes in Perl 6.e language
+from Perl 6.d version. A particular implementation of the language
+may contain additional changes; please consult with the changelog for your
+implementation.
+
+At the same time, a particular implementation may have had certain features
+already implemented during the previous versions period. This ChangeLog concerns
+itself with new features added to the specification on a language level and not
+the status of their implementation in a particular compiler.
+
+### Scope / Target Audience
+
+This ChangeLog is targeted towards language users, to help with preparation to use
+compilers supporting latest language version. Thus, it does not contain every minute
+change to the specification that occurred. Implementations wishing to ensure full
+compliance with the new version of the language specification should execute the
+test suite available at https://github.com/perl6/roast/ and examine any failing tests.
+
+There are new features that did not exist in the previous releases. For full details about them,
+please consult with the language documentation on https://docs.perl6.org/
+Items in *Version-Controlled Changes* section are protected by version pragma and older
+behaviours can be obtained by explicitly using `use v6.<rev>` to request an older language
+version. All other changes do not conflict with the previous revisions and implementations
+may choose to make them available even when an earlier language version is requested.
+
+#### Version-Controlled Changes
+
+_Fill in this section as soon as such changes appear. The following line is a sample from 6.d announce_
+
+- **[6.d]** `&await` no longer blocks *a thread* while waiting
+
+_The following sections are to be filled with upcoming changes in 6.e language_
+
+#### Deprecations
+
+These methods are deprecated in 6.e language and will be removed in 6.f.
+Implementations may choose to emit deprecation warnings or to offer these
+methods for a longer period than 6.f release.
+
+#### New Behaviors
+
+#### New Parameters and Arguments
+
+#### New Routines and Operators
+
+#### New Types
+
+#### New Variables
+
+#### Clarifications of Edge Case/Coercion Behaviour
+
+#### Miscellaneous

docs/release-guide.md

@@ -1,8 +1,5 @@
 # WORKING DRAFT: Language Release Guide
 
-This document contains the process for releasing the major version of the language. It uses
-`6.d` version as example. Adjust that reference for the version you're actually releasing.
-
 Many of the tasks in this document are concurrent. Please read through the entire document.
 
 ## Known Implementations of the Language
@@ -12,20 +9,61 @@ please list the main repository for those in this section:
 
 * Rakudo https://github.com/rakudo/rakudo
 
-## Preparation
+## Terminology
+
+The following terms are used in this document and in other related papers:
+
+- _language revision_ or _revision_
+
+  A set of specifications defining a Perl 6 language variant. Revisions are represented by symbolic names consisting of
+  a single letter of Latin alphabet.
+
+  _Note_ in this document we use `<rev>` to represent a generic revision letter.
+
+- _language version_ or _version_
 
-Release preparation should commence well in advance of planned release date, as there's often
-a large amount of work to perform.
+  Version is a string which represents full revision identification at implementation level. It consist of `6.` prefix
+  followed by revision letter. For example, `6.e`. In the language code and sometimes at other locations the version
+  string might be prefixed with `v` to be unambiguously identified: `v6.e`
 
-### Prep Repo
+- _review_
 
-To keep various communications for the particular release in one place, and separate from general
-spec communications, a [separate repository](https://github.com/perl6/6.d-prep) is created:
+   The process of preparing a new language release.
 
-    https://github.com/perl6/6.d-prep
+- `PREVIEW`
+
+   A modifier to mark language revision which is currently is in _review_ status: `e.PREVIEW`, `6.e.PREVIEW`,
+   `v6.e.PREVIEW`.
+
+## Release Status
+
+_This section contains excerpts from [this discussion](https://github.com/perl6/problem-solving/issues/31)._
+
+Language release process is based on the fact that changes are only allowed to a revision in _review_ status. Once a
+revision is released it becomes _immutable_. From this moment on the only changes allowed are fixes. From the point of
+view of a versioning system like git would look like the following diagram:
+
+```
+             6.<rev> tag
+              V
+---[master]---O-----------------> master now defines 6.<next-rev>.PREVIEW
+               \
+                +---[6.<rev>-errata]
+```
+
+## Preparation
 
-Prior to release, ensure all the planned TODO items and Issues in that repository have
-been addressed.
+Release preparation should commence well in advance of planned release date, as there's often a large amount of work to
+perform.
+
+### Communication Channels
+
+All communications about language development and release process must be done via
+[the problem solving repo](https://github.com/perl6/problem-solving). Prior to release, ensure
+all the planned TODO items and Issues in that repository have been addressed.
+
+_Note:_ 6.d release was using [Prep Repo](https://github.com/perl6/6.d-prep) to manage related
+information. It may still have useful bits worth considering.
 
 ### Spec Review
 
@@ -39,14 +77,14 @@ The commits that aren't part of any release version of the spec can be removed o
 please coordinate with implementation authors, to avoid surprise breakage of code that uses these
 experimental behaviours.
 
-During review, if you file any Issues regarding something that needs to be discussed/decided on
-before release, be sure to tag it with `6.d-review` tag, so that we know what still needs to be
-done before the release.
+During review, if you file any Issues regarding something that needs to be discussed/decided on before release, be sure
+to tag it with `6.<rev> review` tag (`6.e review`, for example), so that we know what still needs to be done before the
+release.
 
 ### TODO Issues
 
-Ensure all open `6.d-review`-tagged Issues in the roast repo have been taken care of before release.
-Check with implementations authors for `6.d-review`-tagged issues in their repositories as well.
+Ensure all open `6.<rev> review`-tagged Issues in the roast repo have been taken care of before release.
+Check with implementations authors for `6.<rev> review`-tagged issues in their repositories as well.
 It's not required that all implementations implement all of the new functionality before the
 language release, but it can be very useful to be aware of the content of those Issues.
 
@@ -91,3 +129,33 @@ ensure it works on new language version. Often, only a small part of the
 new language version is placed behind a version pragma, with the rest of the
 changes being simply clarifications to the past spec. The upgrade guide should
 focus on the version-pragma-protected changes.
+
+## Release Steps
+
+Those steps are to be done when a new language revision is stabilized and time comes for a release:
+
+1. Edit `VERSION` file and remove `.PREVIEW` modifier: `6.<rev>.PREVIEW` -> `6.<rev>`
+1. Finalize revision announce in `docs/announce/6.<rev>.md`
+1. Make sure no `use v6.<rev>.PREVIEW;` pragma has been left behind in a test file.
+
+   Most of the time all is needed is removal of `.PREVIEW` modifier from the version string. Be careful as to make sure
+   the pragma is not an essential part of the test.
+
+1. Place version tag on the tip of `master` branch.
+
+   ```
+   $ git tag 6.<rev>
+   ```
+1. Create revision `-errata` branch.
+
+   ```
+   $ git branch 6.<rev>-errata
+   ```
+
+1. Commit changes
+
+### Starting A New Release.
+
+1. Edit `VERSION` file and change the version to `6.<rev>.PREVIEW`
+1. Create revision announce in `docs/announce/6.<rev>.md`
+1. Commit changes