I would like to propose some changes to improve the process of creating,
voting on, and releasing our source archives.
As far as I can remember, Coho has always been the tool contributors use to
create and vote on releases. Under the hood, the `coho create-archive`
command uses `npm pack` to generate an npm package. This npm package is
what we have traditionally voted on.
Over time, the project has undergone changes, and the contents of the npm
package are no longer exactly the same as they used to be. I would like to
review and determine whether this package is still acceptable as a source
code archive.
Also, according to the release policy, release votes should be based on the
source code archive, not on any build artifacts. Our code is primarily
written in JavaScript, and we do not transpile, minify, or uglify it --
with one exception in the platforms where the "cordova.js" is generated.
===
Here are some of the main changes that changed the output of `npm pack`:
* **We added `package-lock.json` to the repository.**
According to npm documentation, this file is meant to be committed to
source repositories. It was added for various reason but one useful feature
is getting Dependabot to scan for updates and perform security checks.
Should the "source code archive" contain this file? The npm package does
not contain this file as expected.
* **We added `.npmignore`.**
This was added to reduce the published package file size and contained
only production files.
Should the "source code archive" contain the test, test fixtures,
internal development documentations, internal service config files, etc.?
* **We started building `cordova.js` based on a pinned `cordova-js` version
for packaging.**
In the past, we used to generate the `cordova.js` file externally and
then commit it to the platform repository. Since then, we've added
`cordova-js` as a dev dependency to each platform and now build the file
during the npm `prepare` hook script. The `cordova.js` file is generated
and bundled with the npm package but is not in the source code repository.
Should a "source code archive" contain generated files that aren't
present in the repository? This file might be considered part of the build
or compilation process.
===
As a result of these changes, the npm package has gradually stopped being
an exact match of the repository’s contents. Are there any issues with
this? Do we need to change the package that is being voted on? While
investigating, I also looked for ways to improve and simplify our existing
release process overall.
**Proposed Changes:**
1. Refactor the Coho documentation to clarify how to prepare and create the
source package.
1. Could it be as simple as downloading the tag content from GH?
2. Replace the npm publish logic with a GitHub Action Workflow.
1. Trigger the publishing process when a release tag is created.
3. Add a `BUILD.md` file to each repository that explains how to build from
source.
1. While most repos do not have any build logic, it would be consistent
to create a file for all repos. Platforms is the exception where a file is
generated. Platforms need an "npm install" to trigger the "prepare" hook
script for the creation of the `cordova.js` file.
4. No changes are required for the Cordova website or docs, as we will
continue recommending installation via npm registry. Users who prefer
building from source can refer to `BUILD.md`.
5. Vote on the "Draft Tags" Repo Content?
===
Example: Updated Release Process
**Creating a Release Vote:**
1. Create or update the feature branch `{version:major}.{version:minor}.x`.
2. Create a draft tag `draft/{version}` from the feature branch and push it
(or create it via GitHub).
3. Download the `draft/{version}` package content from GitHub tag page.
Select `tar.gz`.
4. Rename downloaded tarball with format
`{repo-name}-{version}-source.tar.gz`.
5. Use GPG to sign tarball.
6. Uploaded files to SVN dev dist for voting:
- `{repo-name}-{version}-source.tar.gz`
- `{repo-name}-{version}-source.tar.gz.asc`
- `{repo-name}-{version}-source.tar.gz.sha512`
**After a Passing Vote:**
1. Move all voted file to release SVN.
2. Create `rel/{version}` tag
- Release tag creations will trigger the `publish.yml` GH Action Workflow
to publish the npm package.
===
The **GitHub Actions workflow** approach looks promising but might require
some additional investigation. Might even need to reach out with ASF to
confirm if its OK. I beleive I heard of other projects having some sort of
release automation so it might be possible. Such a workflow could
significantly reduce the manual steps.
There might also be a slight change to the above example if I include the
Apache ATR, which I also hope to include. This tool should help simplify
the composing, voting, and finalizing of the release.
===
Please share feedback or suggestions.
For reference, see the Apache Software Foundation Release Policy:
https://www.apache.org/legal/release-policy.html. Checkout the
**Artifacts** section of the policy as well.
