verdaccio/CONTRIBUTING.md

Contributing

This guidelines refers to the main (master) that host the v6.x, if you want to contribute to 5.x please read the following link.

We're happy that you're considering contributing!

To help you getting started we've prepared these guidelines for you, any change matter, just do it:

How Do I Contribute?

There are many ways to contribute:

• Report a bug
• Request a feature you think would be great for Verdaccio
• Fixing bugs
• Test and triage bugs reported by others
• Working on requested/approved features
• Improve the codebase (linting, naming, comments, test descriptions, etc...)
• Improve code coverage for unit testing for every module, end to end or UI test (with cypress).

The Verdaccio project is split into several areas, the first three hosted in the main repository:

• Core: The core is the main repository, built with Node.js.
• Website: we use Docusaurus for the website and if you are familiar with this technology, you might become the official webmaster.
• User Interface: The user Interface is based in react and material-ui and looking for front-end contributors.
• Kubernetes and Helm: Ts the official repository for the Helm chart.

There are other areas to contribute, like documentation or translations.

Prepare local setup

Note: The size of the Verdaccio project is quite significant. Unzipped it is about 33 MB. However, a full build with all node_modules installed takes about 2.8 GB of disk space (~190k files)!

Verdaccio uses pnpm as the package manager for development in this repository.

If you are using pnpm for the first time the pnpm configuration documentation may be useful to avoid any potential problems with the following steps.

Note: pnpm uses npm's configuration formats so check that your global .npmrc file does not inadvertently disable package locks. In other words, your .npmrc file should not contain

package-lock=false

This setting would cause the pnpm install command to install incorrect versions of package dependencies and the subsequent pnpm build step would likely fail.

We use corepack to install and use a specific (latest) version of pnpm. Please run the following commands which is use a specific version on Node.js and configure it to use a specific version of pnpm. The version of pnpm is specified in the package.json file in packageManager field.

nvm install
corepack enable
corepack install

pnpm version will be updated mainly by the maintainers but if you would like to set it to a specific version, you can do so by running the following command:

corepack use pnpm@8.9.1

It will update the package.json file with the new version of pnpm in the packageManager field.

With pnpm installed, the first step is installing all dependencies:

pnpm install

Building the project

Each package is independent, dependencies must be build first, run:

pnpm build

Running test

pnpm test

Verdaccio is a mono repository. To run the tests for for a specific package:

cd packages/store
pnpm test

or an specific test in that package:

pnpm test test/merge.dist.tags.spec.ts

or a single test unit:

pnpm test test/merge.dist.tags.spec.ts -- -t 'simple'

Coverage reporting is enabled by default, but you can turn it off to speed up test runs:

pnpm test test/merge.dist.tags.spec.ts -- -t 'simple' --coverage=false

You can enable increased debug output:

DEBUG=verdaccio:* pnpm test

More details in the debug section

Running and debugging

Check the debugging guidelines here

We use debug to add helpful debugging output to the code. Each package has it owns namespace.

Developing with local server

To run the application from the source code, ensure the project has been built with pnpm build, once this is done, there are few commands that helps to run server:

The command pnpm start runs web server on port 8000 and user interface (webpack-server) on port 4873. This is particularly useful if you want to contribute to the UI, since it runs with hot reload. The request to the server are proxy through webpack proxy support through the port 4873.

The user interface is split in two packages, the /packages/plugins/ui-theme and the /packages/ui-components. The ui-components package uses storybook in order to develop component, but if you need to reload ui components with ui-theme do the following.

Go to /packages/ui-component and run pnpm watch to enable babel in watch mode, every change on the components will be hot reloaded in combination with the pnpm start command.

Any change on the server packages, must be build independently (server do not has hot reload, pnpm start should be triggered again).

Any interaction with the server should be done through the port 8000 eg: npm login --registry http://localhost:8000 .

Useful commands

• pnpm debug: Run the server in debug mode --inspect. UI runs too but without hot reload. For automatic break use pnpm debug:break.
• pnpm debug:fastify: To contribute on the fastify migration this is a temporary command for such purpose.
• pnpm website: Build the website, for more commands to run the website, run cd website and then pnpm serve, website will run on port 3000.
• pnpm docker: Build the docker image. Requires docker command available in your system.

Debugging compiled code

Currently you can only run pre-compiled packages in debug mode. To enable debug while running add the verdaccio namespace using the DEBUG environment variable, like this:

DEBUG=verdaccio:* node packages/verdaccio/debug/bootstrap.js

You can filter this output to just the packages you're interested in using namespaces:

DEBUG=verdaccio:plugin:* node packages/verdaccio/debug/bootstrap.js

The debug code is intended to analyze what is happening under the hood and none of the output is sent to the logger module.

See the full guide how to debug with Verdaccio

Testing your changes in a local registry

Once you have perform your changes in the code base, the build and tests passes you can publish a local version:

• Ensure you have built all modules by running pnpm build (or the one you have modified)
• Run pnpm local:publish:release to launch a local registry and publish all packages into it. This command will be alive until server is killed (Control Key + C)

pnpm build
pnpm local:publish:release

The last step consist on install globally the package from the local registry which runs on the default port (4873).

npm i -g verdaccio --registry=http://localhost:4873
verdaccio

If you perform more changes in the source code, repeat this process, there is not hot reloading support.

Feature Request

New feature requests are welcome. Analyse whether the idea fits within scope of the project. Adding in context and the use-case will really help!

Please provide:

• Create a discussion.
• A detailed description the advantages of your request.
• Whether or not it's compatible with npm, pnpm and yarn classic or yarn modern .
• A potential implementation or design
• Whatever else is on your mind! 🤓

Reporting Bugs

Bugs are considered features that are not working as described in documentation.

If you've found a bug in Verdaccio that isn't a security risk, please file a report in our issue tracker, if you think a potential vulnerability please read the security policy .

NOTE: Verdaccio still does not support all npm commands. Some were not considered important and others have not been requested yet.

What's is not considered a bug?

• Third party integrations: proxies integrations, external plugins
• Package managers: If a package manager does not support a specific command or cannot be reproduced with another package manager
• Features clearly flagged as not supported
• Node.js issues installation in any platform: If you cannot install the global package (this is considered external issue)
• Any ticket which has been flagged as an external issue

If you intend to report a security issue, please follow our Security policy guidelines.

Issues

Before reporting a bug please:

• Search for existing issues to see if it has already been reported
• Look for the question label: we have labelled questions for easy follow-up as questions

In case any of those match with your search, up-vote it (using GitHub reactions) or add additional helpful details to the existing issue to show that it's affecting multiple people.

Contributing support

Questions can be asked via Discord

Please use the #contribute channel.

Development Guidelines

It's recommended use a UNIX system for local development, Windows dev local support is not being tested and might not work. To ensure a fast code review and merge, please follow the next guidelines:

Any contribution gives you the right to be part of this organization as collaborator and your avatar will be automatically added to the contributors page.

Pull Request

Submitting a Pull Request

The following are the steps you should follow when creating a pull request. Subsequent pull requests only need to follow step 3 and beyond.

1. Fork the repository on GitHub
2. Clone the forked repository to your machine
3. Make your changes and commit them to your local repository
4. Rebase and push your commits to your GitHub remote fork/repository
5. Issue a Pull Request to the official repository
6. Your Pull Request is reviewed by a committer and merged into the repository

NOTE: While there are other ways to accomplish the steps using other tools, the examples here will assume most actions will be performed via git on command line.

For more information on maintaining a fork, please see the GitHub Help article titled Fork a Repo, and information on rebasing.

Make Changes and Commit

Caveats

Feel free to commit as much times you want in your branch, but keep on mind on this repository we git squash on merge by default, as we like to maintain a clean git history.

Before Push

Before committing or push, you must ensure there are no linting errors and all tests passes. To do verify, run these commands before creating the PR:

pnpm lint
pnpm format
pnpm build
pnpm test

note: eslint and formatting are run separately, keep code formatting before push.

All good? Perfect! You should create the pull request.

Commit Guidelines

On a pull request, commit messages are not important, please focus on document properly the pull request content. The commit message will be taken from the pull request title, it is recommended to use lowercase format.

Adding a changeset

We use changesets in order to generate a detailed Changelog as possible.

Adding a changeset with your Pull Request is essential if you want your contribution to get merged (unless it does not affect functionality or user-facing content, eg: docs, readme, adding test or typo/lint fixes). To create a changeset please run:

pnpm changeset

Then select the packages you want to include in your changeset navigating through them and press the spacebar to check it, on finish press enter to move to the next step.

🦋  Which packages would you like to include? …
✔ changed packages
 changed packages
  ✔ @verdaccio/api
  ✔ @verdaccio/auth
  ✔ @verdaccio/cli
  ✔ @verdaccio/config
  ✔ @verdaccio/commons-api

The next question would be if you want a major bump. This is not the usual scenario, most likely you want a patch, and in that case press enter 2 times (to skip minor)

🦋  Which packages should have a major bump? …
✔ all packages
  ✔ @verdaccio/config@5.0.0-alpha.0

Once you have the desired bump you need, the CLI will ask for a summary. Here you have full freedom on what to include:

🦋  Which packages would you like to include? · @verdaccio/config
🦋  Which packages should have a major bump? · No items were selected
🦋  Which packages should have a minor bump? · No items were selected
🦋  The following packages will be patch bumped:
🦋  @verdaccio/config@5.0.0-alpha.0
🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
🦋  Summary ›

The last step is to confirm your changeset or abort the operation:

🦋  Is this your desired changeset? (Y/n) · true
🦋  Changeset added! - you can now commit it
🦋
🦋  If you want to modify or expand on the changeset summary, you can find it here
🦋  info /Users/user/verdaccio.clone/.changeset/light-scissors-smell.md

Once the changeset is added (all will have an unique name) you can freely edit using markdown, adding additional information, code snippets or whatever else you consider to be relevant.

All that information will be part of the changelog. Be concise but informative! It's recommended to add your nickname and GitHub link to your profile.

PRs that do not follow the commit message guidelines will not be merged.

Update Tests

Any change in source code must include test updates.

If you need help with how testing works, please refer to the following guide .

If you are introducing new features, you MUST include new tests. PRs for features without tests will not be merged.

Translations

All translations are provided by the crowdin platform, https://translate.verdaccio.org/

If you want to contribute by adding translations, create an account (GitHub could be used as fast alternative), in the platform you can contribute to two areas, the website or improve User Interface translations.

Languages with less the 40% of translations available are excluded by the build system.

If a language is not listed, ask for it in the Discord channel #contribute channel.

For adding a new language on the UI follow these steps:

1. Ensure the language has been enabled, must be visible in the crowdin platform.
2. Find in the explorer the file en.US.json in the path packages/plugins/ui-theme/src/i18n/crowdin/ui.json and complete the translations, not need to find approval on this.
3. Into the project, add a new field into packages/plugins/ui-theme/src/i18n/crowdin/ui.json file, in the section lng, the new language, eg: { lng: {korean:"Korean"}}. (This file is English based, once the PR has been merged, this string will be available in crowdin for translate to the targeted language).
4. Add the language, flag icon, and the menu key fort he new language eg: menuKey: 'lng.korean' to the file packages/plugins/ui-theme/src/i18n/enabledLanguages.ts.
5. For local testing, read packages/plugins/ui-theme/src/i18n/ABOUT_TRANSLATIONS.md.
6. Add a changeset file, see more info below.

Develop Plugins

Plugins are add-ons that extend the functionality of the application.

If you want to develop your own plugin:

1. Check whether there is a legacy Sinopia plugin for the feature that you need via npmjs
2. Keep in mind the life-cycle to load a plugin
3. You are free to host your plugin in your repository
4. Provide a detailed description of your plugin to help users understand how to use it