I don't think our NPM tarball generation should change, but I do think
you're actually right in that it's not exactly 100% compliant with
Apache's source release policy.
We can probably archive the repository as a "snapshot" for a source
release. This archive probably should exclude node_modules and the
`.git` folder, but otherwise be representative of what you'd get if you
git checkout the repository release tag. Not against .tar.gz tarball
but for windows users, we probably should have a zip option available.
Having a .tar.gz available would be nice for unix users, but not
strictly necessary. Maybe GH already offers somethings that we can use
to do this.
**We added `package-lock.json` to the repository.**
Yes. If someone downloads a source release, the package-lock will allow
them to replicate the node_modules dependency tree as it was authored
during release. I think that's important for a source archive.
**We added `.npmignore`.**
Yes. If someone downloads the source release with the intent to pack
their own npm tarball. Having this file necessary to properly replicate
produced NPM tarballs.
**We started building `cordova.js` based on a pinned `cordova-js`
version
for packaging.**
No. I think source archives should only include authored source files,
not generated files. Assuming the user has the proper underlying SDK
(aka NodeJS/NPM), then they can npm install the dependencies, and build
the generated bits themselves.
> While most repos do not have any build logic
This is true today, but I personally hate how Cordova plugins are
authored and I still want to explore a workflow that includes having a
native project(s) for plugin development, something that I think has
several benefits. There were technical and policy challenges and I
think these proposed changes would actually solve the policy challenges
since it will allow plugin releases to include a source package as well
as prebuilt artefacts (...if I can ever find time to get back to that
project.)
The proposed changes are a +1 from me. I'm not sure if this should be
considered a high priority issue, but I think the changes overall is an
improvement.
On Tue, 2025-11-04 at 23:31 +0900, Bryan Ellis wrote:
> 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
