docs: update contribution guidelines, scripts to debug and additional notes (#1918)

* chore: debug improments

* update guides

* docs: update contribution guidelines

* chore: add debug notest

* chore: format code

.github/workflows/ci.yml

@@ -7,6 +7,7 @@ on:
       - 'changeset-release/5.x'
   pull_request:
     paths:
+      - .changeset/**
       - .github/workflows/ci.yml
       - 'packages/**'
       - 'jest/**'

.gitignore

@@ -3,6 +3,7 @@ verdaccio-*.tgz
 .DS_Store
 build/
 .eslintcache
+dist/
 
 ### Test
 

.vscode/launch.json

@@ -4,6 +4,13 @@
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
+    {
+      "name": "Verdaccio Debug",
+      "port": 9229,
+      "request": "attach",
+      "skipFiles": ["<node_internals>/**"],
+      "type": "pwa-node"
+    },
     {
       "type": "node",
       "request": "launch",

CONTRIBUTING.md

@@ -1,86 +1,166 @@
-# Contributing to Verdaccio
+# Contributing
 
-> ⚠️ If you intend to file a PR with a new feature, please use the 5.x branch for it 🥰 . master branch is available only for **bug fixing** and dependencies updates.
+> Any chage matters, whatever the size, just do it.
 
-We are happy that you wish to contribute to this project. For that reason, we
+We are happy that you are willing to contribute. For that reason, we
-present you with this guide.
+have prepared guidelines for you:
 
-Additional information is available on the
+### Contents
-[wiki](https://github.com/verdaccio/verdaccio/wiki).
 
-## Contents
-
-- [Contents](#contents)
 - [How Do I Contribute?](#how-do-i-contribute)
-- [Development](#development)
+- [Getting Started](#getting-started)
 - [Reporting Bugs](#reporting-bugs)
   - [Issue Search](#issue-search)
   - [Check Website For Solution](#check-website-for-solution)
   - [Chat](#chat)
   - [Check If It's Been Fixed](#check-if-its-been-fixed)
 - [Request Features](#request-features)
+
   - [Submitting a Pull Request](#submitting-a-pull-request)
   - [Make Changes and Commit](#make-changes-and-commit)
+  - [Submitting a Pull Request](#submitting-a-pull-request)
+  - [Make Changes and Commit](#make-changes-and-commit)
+
 - [Update Tests](#update-tests)
-- [Develop Plugins](#develop-plugins)
+- [Developing Plugins](#develop-plugins)
 
 ## How Do I Contribute?
 
-There are different ways to contribute, each with a different level
+There are different ways to contribute, each comes with a different levels
-of involvement and technical knowledge required, such as:
+of tasks, such as:
 
-- [Reporting Bugs](#reporting-bugs)
+- Fixing bugs
-- [Request Features](#request-features)
+- Triaging reported bugs by others
-- [Develop Plugins](#develop-plugins)
+- Improve codebase (lint, naming, comments, test descriptions, etc...)
-- [Improve Documentation](http://www.verdaccio.org/docs/en/installation.html)
 
-**Please read this document carefully. It will help maintainers and readers
+Verdaccio has several areas of involvement, which might fit you better, eg:
-in solving your issue(s), evaluating your feature request, etc.**
+
+- **Core**: The [core](https://github.com/verdaccio/verdaccio) is the main repository, built with **Node.js**.
+- **Website**: we uses **Gatsby.js** 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
 
-Development guides can be found on the [wiki](https://github.com/verdaccio/verdaccio/wiki):
+Verdaccio uses [_pnpm_](https://pnpm.js.org/) as package manager for development in this repository. Please install the latest one:
 
-- [Building the project](https://github.com/verdaccio/verdaccio/wiki/Build-Source-Code)
+```
-- [Running, debugging, and testing](https://github.com/verdaccio/verdaccio/wiki/Running-and-Debugging-tests)
+npm i -g pnpm
+```
+
+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, for running an specific test or package go the specific package eg:
+
+```
+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
+
+```js
+pnpm test test/merge.dist.tags.spec.ts -- -t 'simple'
+```
+
+The coverage is enabled by default, to speed up test running
+
+```
+pnpm test test/merge.dist.tags.spec.ts -- -t 'simple' --coverage=false
+```
+
+To increase debug output, we use `debug`, to enable it in your test just add
+
+```
+DEBUG=verdaccio* pnpm test
+```
+
+More details in the debug section
+
+### Running and debugging
+
+We uses [`debug`](https://www.npmjs.com/package/debug) for debug outcome. Each package has it owns namespace.
+
+#### Debugging compiled code
+
+Currently you can only run in debug mode pre-compiled packages, to enable debug while running add the `verdaccio` namespace using the `DEBUG` environment variable, like this:
+
+```
+DEBUG=verdaccio:* node packages/verdaccio/debug/bootstrap.js
+```
+
+On this way can be reviewed every package, but if you need to filter out and display more specific output, increase the name space filter.
+
+```
+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 gathered with the logger module.
 
 ## Reporting Bugs
 
-We welcome clear, detailed bug reports.
+**Bugs are considered features that are not working as described in documentation.**
-
-**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
+> **NOTE: Verdaccio still does not support all npm commands. Some were not
-considered important and others have not been requested yet.**
+> considered important and others have not been requested yet.**
+
+### Read the documentation
+
+Check whether you are using the software in the way is documented [documentation](http://www.verdaccio.org/docs/en/installation.html).
+
+### 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 mananger.
+- _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 the flagged as [external issue](https://github.com/verdaccio/verdaccio/labels/external-issue).
+
+If you intent to report a **security** issue, please follow our [Security policy guidelines](https://github.com/verdaccio/verdaccio/security/policy).
 
 ### Issue Search
 
-Search to see if it has already been reported via
+Before consider report a bug, please follow this steps before:
-the issue search.
 
-Additionally, we have labelled questions for easy follow-up as [questions](https://github.com/verdaccio/verdaccio/labels/question).
+- Search if has already been reported via the issue search.
+- Look for the **question** label: we have labelled questions for easy follow-up as [questions](https://github.com/verdaccio/verdaccio/labels/question).
 
-If so, up-vote it (using GitHub reactions) or add additional helpful details to
+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.
-the existing issue to show that it's affecting multiple people.
-
-### Check Website For Solution
-
-Some of the most popular topics can be found in our website(http://www.verdaccio.org/docs/en/installation.html)
 
 ### Chat
 
 Questions can be asked via [Discord](http://chat.verdaccio.org/)
 
-**Please use the `#questions#` and `#development` channels.**
+**Please use the `#help` channel.**
-
-### Check If It's Been Fixed
-
-Check if the issue has been fixed — try to reproduce it using the latest
-`master` or development branch in the repository.
 
 ## Request Features
 
@@ -90,10 +170,16 @@ the project. Then, detail your request, ensuring context and use case is provide
 **Please provide:**
 
 - A detailed description the advantages of your request
-- Whether or not it's compatible with `npm` and `yarn`
+- 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 you have in your mind 🤓
 
+##Contributing
+
+This is the most exciting part, when you became a Verdaccio contributor 🙌🏼, please to ensure a fast code review and merge, 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.
@@ -116,25 +202,30 @@ 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, any other way is forbidden since we intent to have a clean git history.
+
 #### Before Commit
 
 Before committing, **you must ensure there are no linting errors and
 all tests pass.**
 
-To do this, run all tests (including e2e):
+To do this, run these commands before create the PR:
 
 ```bash
-yarn test:all
+pnpm lint
+pnpm format
+pnpm build
+pnpm test
 ```
 
-Then, and only then, you can create your pull request.
+> note: eslint and formatting are running separately, keep code formatting before push.
+
+All good? perfect, then you should create the pull request.
 
 #### Commit Guidelines
 
-We follow the [conventional commit messages](https://conventionalcommits.org/)
-convention in order to automate CHANGELOG generation and to automate
-semantic versioning.
-
 For example:
 
 - `feat: A new feature`
@@ -162,6 +253,66 @@ and `chore:` are valid but have no effect on versioning. **It would be great if
 
 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 uses [changesets](https://github.com/atlassian/changesets) in order to generate a detailed Changelog as possible.
+
+Add a changeset with your Pull Request is essencial if you want your contribution get merged. 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/dev-commons
+  ✔ @verdaccio/config
+  ✔ @verdaccio/commons-api
+```
+
+The next question would be if you want a _major bump_, this is not the usual scenario, most likely would be a patch, 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 the desired bump you need, the CLI will ask for a summary, here you have fully freedom 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 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 what you consider is relevant.
+
+All that information will be part of the **changelog**, be consice but informative. It is considered a good option 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
@@ -173,15 +324,6 @@ If you need help with how testing works, please [refer to the following guide](h
 **If you are introducing new features, you MUST include new tests. PRs for
 features without tests will not be merged.**
 
-Things excluded from tests:
-
-- Documentation
-- Website
-- Build
-- Deployment
-- Assets
-- Flow types
-
 ## Develop Plugins
 
 Plugins are add-ons that extend the functionality of the application.
@@ -191,5 +333,5 @@ 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 or ours (just ask)
+3. You are free to host your plugin in your repository
-4. Provide a detailed description of your plugin to help users understand it
+4. Provide a detailed description of your plugin to help users understand how to use it.

debug/.babelrc

@@ -1,4 +0,0 @@
-{
-  "extends": "../.babelrc",
-  "debug": true
-}

debug/DEBUGGING.md

@@ -1,20 +0,0 @@
-# Debuging Documentation
-
-## Debugging tests
-
-### Running a single test
-
-```bash
-yarn test test/integration/package.spec.ts --runInBand
-```
-
-Using `--runInBand` allows you to see the `console.log` prints, without that `jest` hidde them.
-
-#### Display additional information
-
-You can take advance of `debug` module used by many dependencies, eg:
-
-- `supertest`: `DEBUG=superagent yarn test test/integration/package.spec.ts --runInBand`
-- `express`: `DEBUG=express:* yarn test test/integration/package.spec.ts --runInBand`
-- `nock`: `DEBUG=nock yarn test test/integration/package.spec.ts --runInBand`
-- All of if: `DEBUG=* yarn test test/integration/package.spec.ts --runInBand`

debug/bootstrap.js

@@ -1,6 +0,0 @@
-// this file aims to help local debugging with hot transpilation
-require('@babel/register')({
-  extensions: ['.ts', '.js'],
-});
-
-require('../packages/cli/src/index');

debug/debug.js

@@ -1 +0,0 @@
-require('@verdaccio/cli');

debug/package.json

@@ -1,9 +0,0 @@
-{
-  "name": "debug",
-  "private": true,
-  "version": "1.0.0",
-  "dependencies": {
-    "@verdaccio/babel-preset": "9.4.0",
-    "@verdaccio/cli": "5.0.0-alpha.0"
-  }
-}

package.json

@@ -111,6 +111,8 @@
     "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,yml,yaml,md}\"",
     "lint": "eslint \"**/*.{js,jsx,ts,tsx}\"",
     "test": "pnpm recursive test",
+    "start": "node packages/verdaccio/debug/bootstrap.js",
+    "debug": "node  --inspect packages/verdaccio/debug/bootstrap.js",
     "test:e2e:cli": "cross-env NODE_ENV=test jest --config ./test/e2e-cli/jest.config.e2e.cli.js --passWithNoTests",
     "website:lint": "cd website && yarn lint",
     "website:develop": "cd website && yarn develop",

packages/verdaccio/debug/DEBUGGING.md

@@ -0,0 +1,56 @@
+# Debugging Documentation
+
+This section intend to provide additional information in order to debug the application.
+
+## Debugging tests
+
+Verdaccio uses [**jest**](https://jestjs.io/en/), the following guidelines might be useful for you:
+
+- https://jestjs.io/docs/en/troubleshooting#debugging-in-webstorm
+- https://jestjs.io/docs/en/troubleshooting#debugging-in-vs-code
+- https://jestjs.io/docs/en/cli#--debug
+
+### Running a single test
+
+```bash
+pnpm test test/integration/package.spec.ts -- --runInBand
+```
+
+Using `--runInBand` allows you to see the `console.log` prints, without that `jest` hide them.
+
+Display `debug` output provided for each module:
+
+```
+DEBUG=verdaccio* pnpm test -- --debug --runInBand
+```
+
+> If you don't use `--runInBand` the `debug` code won't have color.
+
+### Running the app in debug mode
+
+```
+➜ pnpm run debug
+Scope: current workspace package
+
+> @ debug /Users/jpicado/projects/verdaccio.master.git
+> node  --inspect packages/verdaccio/debug/bootstrap.js
+
+Debugger listening on ws://127.0.0.1:9229/a31eaf3f-4d4f-4302-a677-a510f14f1ae9
+For help, see: https://nodejs.org/en/docs/inspector
+ warn --- http address - http://localhost:4873/ - verdaccio/5.0.0
+```
+
+The next step would be hook an inspector:
+
+- https://nodejs.org/en/docs/guides/debugging-getting-started/
+- Using the included _task_ with Visual Code `.vscode/launch.json` named _Verdaccio Debug_.
+
+#### Display additional information
+
+You can take advance of `debug` module used by many dependencies, including Verdaccio, eg:
+
+- `babel:*`: `DEBUG=superagent yarn test test/integration/package.spec.ts --runInBand`
+- `supertest`: `DEBUG=superagent yarn test test/integration/package.spec.ts --runInBand`
+- `express`: `DEBUG=express:* yarn test test/integration/package.spec.ts --runInBand`
+- `nock`: `DEBUG=nock yarn test test/integration/package.spec.ts --runInBand`
+- All of if: `DEBUG=* yarn test test/integration/package.spec.ts --runInBand` (_this can be really vebose_)