verdaccio/CONTRIBUTING.md

# Contributing

> Any change matters, whatever the size, just do it.

We're happy that you're considering contributing! To help, we've prepared these
guidelines for you:

**Table of Contents**

- [Contributing](#contributing)
  - [How Do I Contribute?](#how-do-i-contribute)
  - [Development Setup](#development-setup)
    - [Building the project](#building-the-project)
    - [Running test](#running-test)
    - [Running and debugging](#running-and-debugging)
    - [Debugging compiled code](#debugging-compiled-code)
  - [Reporting Bugs](#reporting-bugs)
    - [Read the documentation](#read-the-documentation)
    - [What's is not considered a bug?](#whats-is-not-considered-a-bug)
    - [Issue Search](#issue-search)
    - [Chat](#chat)
  - [Translations](#translations)
  - [Request Features](#request-features)
  - [Contributing Guidelines](#contributing-guidelines)
    - [Submitting a Pull Request](#submitting-a-pull-request)
    - [Make Changes and Commit](#make-changes-and-commit)
      - [Caveats](#caveats)
      - [Before Commit](#before-commit)
      - [Commit Guidelines](#commit-guidelines)
    - [Adding a changeset](#adding-a-changeset)
    - [Update Tests](#update-tests)
  - [Develop Plugins](#develop-plugins)

## How Do I Contribute?

There are many ways to contribute:

- Report a bug
- Request a feature you think would be great for Verdaccio
- Fix bugs
- Test and triage bugs reported by others
- Work on requested/approved features
- Improve the codebase (linting, naming, comments, test descriptions, etc...)

The Verdaccio project is split into several areas:

- **Core**: The [core](https://github.com/verdaccio/verdaccio) is the main repository, built with **Node.js**.
- **Website**: we use [**Docusaurus**](https://docusaurus.io/) for the **website** and if you are familiar with this technology, you might become the official webmaster.
- **User Interface**: The [user Interface](https://github.com/verdaccio/ui) is based in **react** and **material-ui** and looking for front-end contributors.
- **Kubernetes and Helm**: Ts the official repository for the [**Helm chart**](https://github.com/verdaccio/charts).

> There are other areas to contribute, like documentation, translation which are
> not hosted on this repo but check the last section of this notes for further
> information.

## Development Setup

Verdaccio uses [pnpm](https://pnpm.io) as the package manager for development in this repository.

If you are using pnpm for the first time the [pnpm configuration documentation](https://pnpm.io/configuring) 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.

To begin your development setup, please install the latest version of pnpm globally:

```
npm i -g pnpm
```

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

```
pnpm install
```

### Building the project

To build the project 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`](https://www.npmjs.com/package/debug) output:

```
DEBUG=verdaccio:* pnpm test
```

More details in the debug section

### Running and debugging

> Check the debugging guidelines [here](https://github.com/verdaccio/verdaccio/wiki/Debugging-Verdaccio)

We use [`debug`](https://www.npmjs.com/package/debug) to add helpful debugging
output to the code. Each package has it owns namespace.

#### Useful Scripts

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:

- `pnpm start`: Run the server and the UI with `concurrently`, the
  server runs in the port `8000` and the UI on the port `4873`. This command
  is useful if you want to contribute mostly on the UI.
- `pnpm debug`: Run the server in debug mode `--inspect`, the UI is included but does not have hot reload. For automatic break use `pnpm debug:break`.
- `pnpm debug:fastify`: To contribute on the [fastify migration](https://github.com/verdaccio/verdaccio/discussions/2155) 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.

## 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](https://github.com/verdaccio/verdaccio/issues).

> **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 beed flagged as an [external issue
  ](https://github.com/verdaccio/verdaccio/labels/external-issue)

If you intend to report a **security** issue, please follow our [Security policy
guidelines](https://github.com/verdaccio/verdaccio/security/policy).

### Issue Search

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](https://github.com/verdaccio/verdaccio/labels/question)

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.

### Chat

Questions can be asked via [Discord](https://discord.gg/7qWJxBf)

**Please use the `#help` channel.**

## Translations

All translations are provided by the `crowdin` platform:
[https://translate.verdaccio.org/](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.

If a language is not listed, ask for it in the [Discord](https://discord.gg/7qWJxBf) 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](https://www.npmjs.com/package/country-flag-icons), 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.

## Request Features

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:**

- A detailed description the advantages of your request
- Whether or not it's compatible with `npm`, `pnpm` and [_yarn classic_
  ](https://github.com/yarnpkg/yarn) or [_yarn berry_
  ](https://github.com/yarnpkg/berry).
- A potential implementation or design
- Whatever else is on your mind! 🤓

## Contributing Guidelines

It's very exciting to become a Verdaccio contributor 🙌🏼. 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_.

### 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](https://help.github.com/articles/fork-a-repo/), and
information on [rebasing](https://git-scm.com/book/en/v2/Git-Branching-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 Commit

Before committing, **you must ensure there are no linting errors and
all tests pass.** To do this, run these commands before create the PR:

```bash
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

For example:

- `feat: A new feature`
- `fix: A bug fix`

A commit of the type feat introduces a new feature to the codebase (this
correlates with MINOR in semantic versioning).

e.g.:

```
feat: xxxxxxxxxx
```

A commit of the type fix patches a bug in your codebase (this correlates with
PATCH in semantic versioning).

e.g.:

```
fix: xxxxxxxxxxx
```

Commits types such as as `docs:`,`style:`,`refactor:`,`perf:`,`test:` and
`chore:` are valid but have no effect on versioning: **please use them!**

All commits message are going to be validated when they are created using
_husky_ hooks.

> Please try to provide one single commit to help a clean and easy merge process

### Adding a changeset

We use [changesets](https://github.com/atlassian/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 is a change that does not affect library
functionality, eg: typo, docs, readme, add additional test or linting code). 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
](https://github.com/verdaccio/verdaccio/wiki/Running-and-Debugging-tests).

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

## 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](https://www.npmjs.com/search?q=sinopia)
2. Keep in mind the [life-cycle to load a plugin
   ](https://verdaccio.org/docs/en/dev-plugins)
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