> 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.
I believe Step 3 of the proposed change for "Creating a Release Vote" will
cover this. The idea is to first create the draft tag—either through Git
commands or via the GitHub website—and then, from the GitHub website,
download the tag's tarball. GitHub provides both ".tar.gz" and ".zip"
formats. The GitHub CLI and API can also be used to fetch these tarballs.
===
Additional Developer Related Notes:
We might need to test and review the extracted output to confirm which
format is preferred.
For example, if we extract the tarballs obtained from the GitHub CLI or
API, the folder name will follow a pattern such as:
{org-name}-{repo-name}-{short-commit-hash}
If we extract the tarballs downloaded from the GitHub website, the folder
name will instead follow the pattern:
{repo-name}-{tag-name}
For instance, if the draft tag is "draft/1.0.0", then extracting the
source will produce a folder named "repo-name-draft-1.0.0". I don't think
this would be an ideal name to see coming from an official release,
whereas a name like "apache-repo-name-1c1cdd1" might be acceptable.
Note that the tarball itself can be named correctly — it's the extracted
folder name that I'm describing above.
To avoid using the GitHub website and stay entirely within the terminal,
the GitHub CLI could replace some of the existing "coho" commands, but it
would require the GitHub CLI to be installed as a new tool. Alternatively,
the GitHub API could also replace "coho" commands by using tools like
"wget" or "curl", or by updating "coho" itself.
The GitHub API approach sounds promising, as it can be called without
authentication for public repositories, though it is limited to 60 requests
per hour. Also, the extracted folder name would not seem as a "draft".
On Wed, Nov 5, 2025 at 1:04 AM Norman Breau <[email protected]>
wrote:
> 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]
>
>
