Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nyxb/contribute
📝 Contribution Guide for most of Nyxb's projects
https://github.com/nyxb/contribute
contribute
Last synced: 12 days ago
JSON representation
📝 Contribution Guide for most of Nyxb's projects
- Host: GitHub
- URL: https://github.com/nyxb/contribute
- Owner: nyxb
- Created: 2023-05-15T10:28:24.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-10-22T14:28:49.000Z (over 1 year ago)
- Last Synced: 2024-11-21T04:44:13.709Z (2 months ago)
- Topics: contribute
- Homepage: https://nyxb.xyz
- Size: 5.86 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Contribution Guide
Hey there! We are really excited that you are interested in contributing. This is a general contribution guide for most of [Nyxb's projects](https://nyxb.site/projects). Before submitting your contribution, please make sure to take a moment and read through the following guide:
## 👨💻 Repository Setup
We use [`pnpm`](https://pnpm.io/) for most of the projects, and maybe a few with [`yarn`](https://classic.yarnpkg.com/), we highly recommend you install [`nyxi`](https://github.com/nyxb/nyxi) so you don't need to worry about the package manager when switching across different projects.
We will use `ni`'s commands in the following code snippets. If you are not using it, you can do the conversion yourself: `nyxi = pnpm install`, `nyxr = pnpm run`.
To set the repository up:
| Step | Command |
|-------|--------|
| 1. Install [Node.js](https://nodejs.org/), using the [latest LTS](https://nodejs.org/en/about/releases/) | - |
| 2. [Enable Corepack](#corepack) | `corepack enable` |
| 3. Install [`@antfu/ni`](https://github.com/nyxb/nyxi) | `npm i -g @nyxb/nyxi` |
| 4. Install dependencies under the project root | `ni` |
## 💡 Commands
### `nyxr dev`
Start the development environment.
If it's a Node.js package, it will start the build process in watch mode, or [stub the passive watcher when using `unbuild`](https://nyxb.blog/en/tech-topics/esm-and-cjs).
If it's a frontend project, it usually starts the dev server. You can then develop and see the changes in real time.
### `nyxr play`
If it's a Node.js package, it starts a dev server for the playground. The code is usually under `playground/`.
### `nyxr build`
Build the project for production. The result is usually under `dist/`.
### `nyxr lint`
We use [ESLint](https://eslint.org/) for **both linting and formatting**. It also lints for JSON, YAML and Markdown files if exists.
You can run `nyxr lint --fix` to let ESLint formats and lints the code.
Learn more about the [ESLint Setup](#eslint).
[**We don't use Prettier**](#no-prettier).
### `nyxr test`
Run the tests. We mostly using [Vitest](https://vitest.dev/) - a replacement of [Jest](https://jestjs.io/).
You can filter the tests to be run by `nyxr test [match]`, for example, `nyxr test foo` will only run test files that contain `foo`.
Config options are often under the `test` field of `vitest.config.ts` or `vite.config.ts`.
Vitest runs in [watch mode by default](https://vitest.dev/guide/features.html#watch-mode), so you can modify the code and see the test result automatically, which is great for [test-driven development](https://en.wikipedia.org/wiki/Test-driven_development). To run the test only once, you can do `nyxr test --run`.
For some projects, we might have multiple types of tests set up. For example `nyxr test:unit` for unit tests, `nyxr test:e2e` for end-to-end tests. `nyxr test` commonly run them together, you can run them separately as needed.
### `nyxr docs`
If the project contains documentation, you can run `nyxr docs` to start the documentation dev server. Use `nyxr docs:build` to build the docs for production.
### `nyxr`
For more, you can run bare `nyxr`, which will prompt a list of all available scripts.
## 🙌 Sending Pull Request
### Discuss First
Before you start to work on a feature pull request, it's always better to open a feature request issue first to discuss with the maintainers whether the feature is desired and the design of those features. This would help save time for both the maintainers and the contributors and help features to be shipped faster.
For typo fixes, it's recommended to batch multiple typo fixes into one pull request to maintain a cleaner commit history.
### Commit Convention
We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages, which allows the changelog to be auto-generated based on the commits. Please read the guide through if you aren't familiar with it already.
Only `fix:` and `feat:` will be presented in the changelog.
Note that `fix:` and `feat:` are for **actual code changes** (that might affect logic).
For typo or document changes, use `docs:` or `chore:` instead:
- ~~`fix: typo`~~ -> `docs: fix typo`
### Pull Request
If you don't know how to send a Pull Request, we recommend reading [the guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
When sending a pull request, make sure your PR's title also follows the [Commit Convention](#commit-conventions).
If your PR fixes or resolves an existing issue, please add the following line in your PR description (replace `123` with a real issue number):
```markdown
fix #123
```
This will let GitHub know the issues are linked, and automatically close them once the PR gets merged. Learn more at [the guide](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword).
It's ok to have multiple commits in a single PR, you don't need to rebase or force push for your changes as we will use `Squash and Merge` to squash the commits into one commit when merging.
## 🧑🔧 Maintenance
This section is for maintainers with write access, or if you want to maintain your own forks.
### Update Dependencies
Keeping dependencies up-to-date is one of the important aspects to keep projects alive and getting latest bug fixes on time. We recommend to update dependencies in weekly or bi-weekly intervals.
We use [`taze`](https://github.com/antfu/taze) to update the dependencies manually most of the time. As deps updating bots like [Dependabot](https://github.com/dependabot) or [Renovate](https://renovatebot.com/) could be a bit annoying when you have a lot projects.
With `taze`, you can run `taze major -Ir` to check and select the versions to update interactive. `-I` stands for `--interactive`, `-r` stands for `--recursive` for monorepo.
After bumpping, we install them, runing build and test to verify nothing breaks before pushing to main.
### Releasing
Before you do, make sure you have lastest git commit from upstream and all CI passes.
For most of the time, we do `nr release`. It will prompts a list for the target version you want to release. After select, it will bump your package.json and commit the changes with git tag, powered by [`bumping`](https://github.com/nyxb/bumping).
There are two kinds of publishing setup, either of them are done by `nyxr release` already.
#### Build Locally
For this type of setup, the building and publishing process is done on your local machine. Make sure you have your local [`npm` logged in](http://npm.github.io/installation-setup-docs/installing/logging-in-and-out.html) before doing that.
In `package.json`, we usually have:
```json
{
"scripts": {
"prepublishOnly": "nyxr build"
}
}
```
So whenever you run `npm publish`, it will make sure you have the latest change in the distribution.
#### Build on CI
For complex projects that take long time to build, we might move the building and publishing process to CI. So it doesn't block your local workflow.
They will be triggered by the `v` prefixed git tag added by `bumping`. The action is usually defined under `.github/workflows/release.yml`
> When maintaining your own fork, you might need to see `NPM_TOKEN` secret to your repository for it to publish the packages.
Changelogs are always generated by GitHub Actions.
## 📖 References
### Corepack
#### TL;DR
To enable it, run
```bash
corepack enable
```
You only need to do it once after Node.js is installed.
#### What's Corepack
[Corepack](https://nodejs.org/api/corepack.html) makes sure you are using the correct version for package manager when you run corresponding commands. Projects might have `packageManager` field in their `package.json`.
Under projects with configuration as shown on the right, corepack will install `v7.1.5` of `pnpm` (if you don't have it already) and use it to run your commands. This makes sure everyone working on this project have the same behavior for the dependencies and the lockfile.
`package.json`
```jsonc
{
"packageManager": "[email protected]"
}
```
### ESLint
We use [ESLint](https://eslint.org/) for both linting and formatting with [`@nyxb/eslint-config`](https://github.com/nyxb/eslint-config).
#### IDE Setup
We recommend using [VS Code](https://code.visualstudio.com/) along with the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint).
With the settings on the right, you can have auto fix and formatting when you save the code you are editing.
VS Code's `settings.json`
```json
{
"editor.codeActionsOnSave": {
"source.fixAll": false,
"source.fixAll.eslint": true
}
}
```
### No Prettier
Since ESLint is already configured to format the code, there is no need to duplicate the functionality with Prettier ([*Why I don't Use Prettier*](https://nyxb.blog/en/tech-topics/a-double-edged-sword-for-code-formatting)). To format the code, you can run `nyxr lint --fix` or referring the [ESLint section](#eslint) for IDE Setup.
If you have Prettier installed in your editor, we recommend you disable it when working on the project to avoid conflict.
## 🗒 Additional Info
In case you are interested in, here is Anthony's personal configrations and setups:
- [nyxb/dotfiles](https://github.com/nyxb/dotfiles) - ZSH configs and other dotfiles
- [nyxb/vscode-settings](https://github.com/nyxb/vscode-settings) - VS Code settings
- [nyxb/eslint-config](https://github.com/nyxb/eslint-config) - ESLint config
CLI Tools
- [nyxi](https://github.com/nyxb/nyxi) - package manager alias
- [esno](https://github.com/nyxb/esno) - TypeScript runner
- [freshdeps](https://github.com/nyxb/freshdeps) - dependency updater
- [bumping](https://github.com/nyxb/bumping) - version bumpper
In addition of `nyxi`, here is a few shell aliases to be even lazier:
```bash
alias d="nyxr dev"
alias b="nyxr build"
alias t="nyxr test"
alias tu="nyxr test -u"
alias p="nyxr play"
alias c="nyxr typecheck"
alias lint="nyxr lint"
alias lintf="nyxr lint --fix"
alias release="nyxr release"
```