Versions, Branches, Releases

README.md

@@ -6,12 +6,24 @@ This repository contains documents describing everything a contributor of Apache
 
 ## Topics
 
-- [Create a minimal reproduction repository](create-reproduction.md)
-- [Deprecation and Archiving of Repositories](deprecation.md)
+### Developing Apache Cordova
+
 - [Testing Cordova](testing.md)
+- [Code Maintenance](code-maintenance.md)
+- [Creating a Release](release-process.md)
+- [Testing a Release](testing-releases.md)
 
 ### Process
 
+- [Deprecation and Archiving of Repositories](deprecation.md)
+- [Versions, Branches and Releases](versions-branches-releases.md)
+
+#### GitHub
+
 - [GitHub Project Boards](github-project-boards.md)
 - [GitHub Labels](github-labels.md)
 - [GitHub Templates](github-templates.md)
+
+### Support
+
+- [Create a minimal reproduction repository](create-reproduction.md)

code-maintenance.md

@@ -0,0 +1,47 @@
+# Code Maintenance
+
+Steps we regularly take to make sure our code is in a good state.
+
+## Licences
+
+[Background information](http://www.apache.org/legal/src-headers.html)
+TODO
+
+### Licence Headers
+
+Ensure license headers are present everywhere:
+
+```bash
+coho audit-license-headers -r android | less
+```
+
+TODO Properly handle this: "Ensure license headers are present everywhere. For reference, see this background. Expect some noise in the output, for example some files from test fixtures will show up."
+
+TODO What to do if not?
+
+### Dependency Licences
+
+Ensure all dependencies and subdependencies have Apache-compatible licenses:
+
+```bash
+coho check-license -r android
+```
+
+TODO What to do if not?
+
+## Dependencies
+
+### `npm outdated --depth=0`
+
+- Variant 1: Pin the outdated dependency in `dependencies` of `package.json`, create issue to update.
+- Variant 2: Update the dependency by creating a Pull Request with the changes.
+
+### `npm audit`
+
+TODO How are results handled?
+
+(Might require running `npm i --package-lock-only` before, and deleting `package-lock.json` afterwards)
+
+### Pinned dependencies
+
+TODO

release-process.md

@@ -0,0 +1,59 @@
+# Release Process Documentation
+
+## Release Process Overview
+
+This describes the _technical_, theoretical steps of a release. (For all the _organizational_ steps and actual commands to execute, please refer to the [Detailed Release Process Documentation](#detailed-release-process-documentation) below.)
+
+- Checkout `master` of the project you want to release
+- Find out if your release requires a release branch (instead of releasing from `master` directly):  
+  a) Are there any commits on `master` that should not be part of the release?  
+  b) If patch release: Is there already a release branch for a previous patch release for this minor version?  
+  c) Do you want to do a patch release to an older minor (`1.2.3` after `1.3.0` has already been released) or a minor release after there was a new major release (`1.7.0` after `2.0.0` has already been released)
+- Only if yes: 
+  - _Create_ a release branch (e.g. `1.2.x`) on the last "good" commit (before the first one that should not be included in the release) or last released tag/commit and _check it out_ (or _check out_ the existing release branch for b))
+  - _Cherry pick_ any further commits from `master` that should be included to the checked out release branch
+  - Do any manual changes that need to be done (e.g. to fix a bug) and _commit_ 
+- Prepare Release
+  - [Code Maintenance](code-maintenance.md)
+  - If minor or major release (and not bumped manually already): Bump minor or major and _commit_
+  - [Test](testing-releases.md)
+    - Fix any regressions and _commit_
+  - Create, curate Release Notes into `RELEASENOTES.md` and _commit_
+- Release
+  - Remove `-dev` suffix in version and Release Notes (and _commit_)
+  - _Tag_ as `vote/x.y.z`
+  - Apache: Create archive and upload to [`dist/dev`](https://dist.apache.org/repos/dist/dev/cordova/)
+  - Bump patch + add `-dev` back (and _commit_)
+  - _Push_ all changes and tag
+- Vote
+  - Other PMC members [test the release](testing-releases.md) and vote
+- On success:
+  - Apache: Promote from [`dist/dev`](https://dist.apache.org/repos/dist/dev/cordova/) to [`dist/release`](https://dist.apache.org/repos/dist/release/cordova/)
+  - Add `x.y.z` release tag
+  - Publish archive (!) to npm
+  - If releasing from release branch: Cherry pick release notes (and possible other commits) to `master`
+  - _Push_ changes and tag
+- On failure:
+  - Remove created tag (and _push_), delete uploaded archive from [`dist/dev`](https://dist.apache.org/repos/dist/dev/cordova/), unbump patch on release branch (and _commit_ and _push_)
+    - TODO ALTERNATIVE: remove tag, delete archive, start from beginning with now a patch release
+    - TODO ALTERNATIVE: https://github.com/apache/cordova-coho/blob/master/docs/platforms-release-process.md#if-the-vote-does-not-pass
+  - Fix problem
+  - Restart at "Release"
+
+This list also does not include steps that are only required for one type of component:
+
+- Platforms: Update `cordova.js`, propagate version number to other platform files (which those are depends on the platform), tag `master` of `cordova-js` with new platform version, make sure documentation is up to date or create PR that can be merged after release, Android only: Publish to Bintray
+- Plugins: Make sure `README.md` is correct
+- Tools: cordova-lib: Update `platformsConfig.json`, all: update cross dependencies between libraries, 
+
+The detailed documentation below does include these at the appropriate locations.
+
+## Detailed Release Process Documentation
+
+This generalized release process is supported and partly automated by our `cordova-coho` CLI tool. As details of this process are different depending on what kind of package you want to release, we have individual detailed release process documentation that contains the actual commands to run:
+
+- [Platforms](https://github.com/apache/cordova-coho/blob/master/docs/platforms-release-process.md)
+- [Plugins](https://github.com/apache/cordova-coho/blob/master/docs/plugins-release-process.md)
+- [Tooling](https://github.com/apache/cordova-coho/blob/master/docs/tools-release-process.md)
+- [Hello World App](https://github.com/apache/cordova-coho/blob/master/docs/app-hello-world-release-process.md)
+- [Coho](https://github.com/apache/cordova-coho/blob/master/docs/coho-release-process.md)

versions-branches-releases.md

@@ -0,0 +1,77 @@
+# Versions, Branches and Releases
+
+This document describes how Apache Cordova versions and manages its packages.
+
+- [Version](#version)
+  * [Version Naming](#version-naming)
+  * [Version Bump](#version-bump)
+- [Branches](#branches)
+  * [Release Branch](#release-branch)
+- [Release](#release)
+  * [Release Preparation](#release-preparation)
+  * [Tags](#tags)
+  * [Apache Process: Votes and Release Tags](#apache-process-votes-and-release-tags)
+  * [Publish](#publish)
+- [Release Process Documentation](#release-process-documentation)
+
+## Version
+
+### Version Naming
+
+- Versions of packages follow simple [Semantic Versioning](https://semver.org/) practices:
+  > Given a version number MAJOR.MINOR.PATCH, increment the:
+  > - MAJOR version when you make incompatible API changes,
+  > - MINOR version when you add functionality in a backwards-compatible manner, and
+  > - PATCH version when you make backwards-compatible bug fixes.
+- A `-dev` suffix is added to versions in repos to indicate unreleased code (as platforms and plugins can be installed from a repository's `master` branch via Cordova CLI). This suffix is only removed during the [release process](#release) and added back with the [version bump](#version-bump).
+
+### Version Bump
+
+The version of a package is "bumped" (increased):
+
+- automatically (after release)
+  - in preparation of next release: bump patch  (`#.#.x`)
+- manually (when it happens or latest before release)
+  - on commits adding new features: bump minor (`#.x.#`)
+  - on commit breaking existing functionality: bump major (`x.#.#`)
+
+If a [release branches](#release-branch) is required, the version bump may happen on the release branch instead of `master`.
+
+## Branches
+
+Apache Cordova uses a variant of [Trunk Based Development](https://trunkbaseddevelopment.com):
+
+- Feature development is done in feature branches or branches of forks. 
+- Those are merged via Pull Requests that integrate their changes back into `master`.
+- [Release branches](#release-branch) are used for releases if necessary.
+
+### Release Branch
+
+Cordova uses release branches for releases only if necessary: If a new patch or minor release from `master` is not possible as it already includes other changes that should or can not be part of the planned release, we create a release branch (e.g. `1.0.x` for an upcoming `1.0.1` patch release, or `2.1.x` for an upcoming `2.1.0` minor release). New changes added in those release branches should be merged back to `master` if applicable (release notes or bug fixes: yes, version number changes: no).
+
+## Release
+
+### Release Preparation
+
+During the release preparation the commit messages of changes that happened are curated into a release notes file.
+
+### Tags
+
+Tags are used to to indicate versions (e.g. `1.1.0`). Tagging happens after all the work for a release has been done.
+
+### Apache Process: Votes and Release Tags
+
+As Cordova is an Apache Software Foundation project, we have some additional special steps during our releases:
+
+- When tagging a "release" you do not use the final release version number, but e.g. `vote/1.1.0` to indicate that this is not a release tag that still has to be voted on.
+- This tag is then archived into an archive and uploaded to a temporary location on the Apache SVN server.
+- Then there is a [release vote on the mailing list](release-voting.md) to determing if the release can happen as planned.
+- Voted on and accepted releases get an additional permanent "release tag" (e.g. `1.1.0`) and the archive is moved to another, permanent location on the Apache SVN server.
+
+### Publish
+
+After a successful vote the tag is also be published to [npm](https://www.npmjs.com/) for developers to use with Cordova CLI.
+
+## Release Process Documentation
+
+The actual release process a committer might follow is documented in [release-process.md](release-process.md). This also describes the software Apache Cordova uses to enable and simplify the release process.