github.com/verdaccio
1
0
Fork 0
mirror of https://github.com/verdaccio/verdaccio.git synced 2024-12-24 21:15:51 +01:00
Code Releases Wiki Activity

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

Browse Source 
* chore: debug improments

* update guides

* docs: update contribution guidelines

* chore: add debug notest

* chore: format code
This commit is contained in:
Juan Picado 2020-09-07 07:36:08 +02:00
parent aa763baec1
commit 8632c3a6d6
11 changed files with 271 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/workflows/ci.yml vendored
View File

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

1
.gitignore vendored
View File

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

7
.vscode/launch.json vendored
View File

@ -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",

266
CONTRIBUTING.md
View File

@ -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
present you with this guide.
We are happy that you are willing to contribute. For that reason, we
have prepared guidelines for you:
Additional information is available on the
[wiki](https://github.com/verdaccio/verdaccio/wiki).
### Contents
## 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
of involvement and technical knowledge required, such as:
There are different ways to contribute, each comes with a different levels
of tasks, such as:
- [Reporting Bugs](#reporting-bugs)
- [Request Features](#request-features)
- [Develop Plugins](#develop-plugins)
- [Improve Documentation](http://www.verdaccio.org/docs/en/installation.html)
- Fixing bugs
- Triaging reported bugs by others
- Improve codebase (lint, naming, comments, test descriptions, etc...)
**Please read this document carefully. It will help maintainers and readers
in solving your issue(s), evaluating your feature request, etc.**
Verdaccio has several areas of involvement, which might fit you better, eg:
- **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
considered important and others have not been requested yet.**
> **NOTE: Verdaccio still does not support all npm commands. Some were not
> 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
the issue search.
Before consider report a bug, please follow this steps before:
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
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)
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](http://chat.verdaccio.org/)
**Please use the `#questions#` and `#development` channels.**
### 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.
**Please use the `#help` channel.**
## 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)
4. Provide a detailed description of your plugin to help users understand it
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.

4
debug/.babelrc
View File

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

20
debug/DEBUGGING.md
View File

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

6
debug/bootstrap.js vendored
View File

@ -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');

1
debug/debug.js
View File

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

9
debug/package.json
View File

@ -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"
}
}

2
package.json
View File

@ -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",

56
packages/verdaccio/debug/DEBUGGING.md Normal file
View File

@ -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_)