CONTRIBUTING.md

Contributing to docker-node

Thank you for your contribution. Here are guidelines for contributing to the docker-node project.

Table of Contents

• Governance and decision making
• Discussion Areas
• Prerequisites
• Pull requests
• Linting
• Link checks
• Version Updates
  • Image Creation Automation
  • Image Creation Manually
• Adding dependencies to the base images

Governance and decision making

Project governance uses consensus seeking. See GOVERNANCE.md for roles and the decision process.

For governance-sensitive or potentially contentious changes, open a PR (or issue) with rationale and allow time for async feedback.

If a final decision cannot be reached via consensus seeking, escalation goes to the Node.js TSC as final arbiter.

Discussion Areas

You can use Node.js channels (prefixed by #nodejs-) in the OpenJSF Slack workspace for discussions.

• #nodejs-distributions covers discussions for this repo (docker-node).

• #nodejs-release is linked to the Node.js Release Working Group responsible for the upstream releases of Node.js used by this repo.

Prerequisites

To contribute to this repo, install:

• git
• Docker
• Node.js LTS version as specified in .node-version

fork and clone this repo, then install npm dependencies. Replace <my-github-username> with the username of your fork in the instructions below:

git clone https://github.com/<my-github-username>/docker-node
cd docker-node
git remote add upstream https://github.com/nodejs/docker-node
git remote update
npm ci # install npm dependencies

Pull requests

Contributions are handled through GitHub pull requests. Branch from the default branch main and create a new branch, for example:

git checkout main
git checkout -b my-branch

Make changes in your branch and then submit your contribution as a pull request (PR), targeting the branch main.

Linting

After making changes, execute the following to check for correct formatting. This runs the linting scripts format:toc:check and format:prettier:check.

npm run lint

To fix any linting issues that are automatically fixable, execute:

npm run lint:fix

Alternatively use any of the following commands to call one of the underlying linting utilities:

Command	Purpose
npm run format:toc	Reformats any Table of Contents
npm run format:toc:check	Read-only Table of Contents check
npm run format:prettier	Reformats multiple types of source code
npm run format:prettier:check	Read-only prettier check

Link checks

Execute the following to check links in Markdown files:

npm run check:markdown-links

If you are running on Microsoft Windows, run the above command in a Git Bash terminal window. Git for Windows includes Git Bash.

Version Updates

New Node.js releases are released as soon as possible.

New npm releases are not tracked. We simply use the npm version bundled in the corresponding Node.js release.

Yarn v1 Classic is no longer maintained upstream, and it is removed when constructing Dockerfiles from templates starting with the Node 26 images.

Alpine Linux latest two releases are used. When Alpine Linux makes a new branch available, which is planned for May and November each year, this branch is adopted as a new base image and it becomes the default for each supported Node.js release line. The lowest previously used Alpine Linux release is dropped for future image builds, so that only the two latest releases are maintained.

Image Creation Automation

• Every 15 minutes, the workflow within the nodejs/docker-node repo checks for new versions of Node.js published to the website's index.json file.
  • If found, it also checks for an unofficial musl/Alpine build.
  • If found, the update script runs
  • The workflow opens a pull request either automatically via nodejs-github-bot or in some cases manually, such as when there is a new major release.
• Another workflow detects the merger of these pull requests and opens a pull request to docker-library/official-images.
• The official images are built and published according to docker's process, resulting in the new images being available on Docker Hub.

Image Creation Manually

Image updates for existing Node.js release lines are created automatically as described above. If there is a problem with the automated process, it may be necessary to create an update PR manually. If you believe there is a need for a manual PR, and you are not a member of the Docker Maintainers or Collaborators team of this repo, please first open an issue to describe the update problem and your suggestion to resolve it.

To set up a version update pull request, see the Pull Requests section above and follow these instructions:

1. Create a version-update branch
2. Run ./update.sh. You can see additional options by using the built-in help documentation with ./update.sh -h. This script will automatically update the appropriate files with the latest versions and checksums.
3. Commit the modified files to the version-update branch and push the branch to your fork.
4. Create a pull request.

When a new Node.js release line is expected, additional preparation is necessary, including updates to the versions.json file and creation of a major version directory, populated with generated files. This task is undertaken by members of the repo team above.

Adding dependencies to the base images

NodeJS is a big ecosystem with a variety of different use cases. The docker images for node are designed to provide the minimum for running core node. Additional dependencies (including dependencies for npm or yarn such as git) will not be included in these base images and will need to be included in descendent image.