docs: update contributing.md and package-generator

CONTRIBUTING.md

@@ -0,0 +1 @@
+docs/src/content/docs/contributing.md

docs/src/content/docs/contributing.md

@@ -3,88 +3,90 @@ title: Contributing
 description: How to contribute to Reatom
 ---
 
-If you want to contribute to improving the library, use the following instructions to create changes:
-
 > **Note:** we prefer English language for all communication.
 
 ## Creating an issue
 
-If you found a bug or want to make an improvement in the library please check whether the same issue already exists in the [list of issues](https://github.com/artalar/reatom/issues). If you don't find the issue there, [create a new one](https://github.com/artalar/reatom/issues/new) including a description of the problem.
+Before creating an issue please ensure that the problem is not [already reported](https://github.com/artalar/reatom/issues).
+
+If you want to report a bug, create a reproduction using StackBlitz or CodeSandbox. If you want to request a feature, add motivation section and some usage examples.
 
 ## Sending a Pull Request
 
-1. 🐙 Fork and clone the repository.
-2. 🗜️ Install dependencies from the root of the repo, `node@18` and `npm@8` required.
- ```bash
- npm i
- ```
- All needed dependencies for all packages will be installed automatically, but only `@reatom/framework` dependencies (`core`, `utils`, `async` and a few more) will be builded.
-3. 🔨 Build needed package from the root of the repo.
- ```bash
- npx turbo run build --filter=PACKAGE_NAME
+1. fork and clone the repository
+2. create a development branch from `v3`
+3. install dependencies from the root of the repo (`node@18` and `npm@8` are required):
+ ```sh
+ npm install
  ```
- Replace `PACKAGE_NAME` with the name of the package you want to build. For example, `npm-react` or `persist`. The [turbo](https://turbo.build) will handle all dependencies and build all required graph.
-4. 🎨 Create a `feature-branch` from `v3` branch that starts from the number of the [created issue](#creating-an-issue).
-5. 🧪 If you want to fix a bug, write reproduction tests first.
-6. 🪄 Make changes.
-7. 🧪 If you added a feature, write tests for it.
-8. 📝 Record the changes according to [conventional rules](#commit-rules).
- ```bash
- $ git commit -m "<type>[optional scope]: <description>"
+ Dependencies are installed for all packages, but only packages included in `@reatom/framework` (`core`, `utils`, `async` etc.) are built.
+4. build the package you are editing from the root of the repo:
+ ```sh
+ npx turbo run build --filter=<PACKAGE_NAME>
  ```
-9. 💍 Send the changes to GitHub and create [Pull Request](https://github.com/artalar/reatom/compare) to the `v3` branch.
-10. 🔗 Link the Pull Request and issue with [keyword](https://help.github.com/en/articles/closing-issues-using-keywords) or provide description with motivation and explanation in the comment. Example: `fix #74`.
-11. ⏳ Wait for a decision about accepting the changes.
+ Replace `<PACKAGE_NAME>` with the relevant package name like `persist` or `npm-react`
+5. [make changes](#coding-guide) and [commit them](#commit-messages)
+6. upload feature branch and create a [Pull Request](https://github.com/artalar/reatom/compare) to merge changes to `v3`
+7. link your PR to the issue using a [closing keyword](https://help.github.com/en/articles/closing-issues-using-keywords) or provide changes description with motivation and explanation in the comment (example: `fix #74`)
+8. wait until a team member responds
 
-## Create a new package
+## Creating a package
 
-We want to grow a huge ecosystem of packages for Reatom and made an adapters for most popular web APIs and NPM libraries. If you want to help with it, please follow the instructions of [Sending a Pull Request](#sending-a-pull-request) section, but on the third step you should add a new package to the `packages` directory We have a handy generator for it, run the following command from the root of the repo and follow the displayed instructions.
+The goal of Reatom ecosystem is to provide adapters for Web APIs and popular npm modules. Therefore, the process of creating a new package is almost identical to editing an existing one ([Sending a Pull Request](#sending-a-pull-request)), but you should also create the package using an interactive script ran in the repository root:
 
-```bash
+```sh
 npm run package-generator
 ```
 
-Edit the `author` field and add yourself to the `maintainers` list of the `package.json` of the new package.
+Add needed dependencies by running `npm install` in your package's directory. If you're making an adapter for a particular npm library (like `@reatom/npm-react` for React), the library should be saved as peer: `npm install --save-peer <LIBRARY>`
+
+<!-- ??? -->
+<!-- To add dependencies, add them manually to the `package.json` of the new package and install them from the root of the repo. -->
+
+### Package naming rule
 
-If you need to add dependencies, add them manually to the `package.json` of the new package and install them from the root of the repo.
+Packages that integrate Reatom with external APIs should have their names prefixed with one of the following strings: `node-`, `npm-`, `web-`. For example, [`@reatom/npm-history`](https://reatom.dev/package/npm-history) provides an adapter for the [`history`](https://npmjs.com/history) package. Similiarly, a potential adapter for [Web History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) would be named `@reatom/web-history`.
 
-## Codestyle rules
+## Coding guide
 
-1. use `// @ts-ignore` if you not sure why error appears or you think it could be better, use `// @ts-expect-error` if you sure that error is a mistake.
+- bug fixes should also add tests that reproduce the addressed bug
+- all new features should be tested and documented
+<!-- - always use `@ts-expect-error` instead of `@ts-ignore` -->
+- use `// @ts-ignore` if you not sure why error appears or you think it could be better, use `// @ts-expect-error` if you sure that error is a mistake <!-- ??? -->
 
-## Commit rules
+## Commit messages
 
-Record the changes made by making comments in accordance with [Conventional Commits](https://conventionalcommits.org).
+Commit messages should follow the [Conventional Commits](https://conventionalcommits.org) specification:
 
 ```
 <type>[optional scope]: <description>
 ```
 
 ### Allowed `<type>`
 
-- **chore** - maintain
-- **ci** - ci configuration
-- **feat** - new feature
-- **fix** - bug fix
-- **docs** - documentation
-- **style** - formatting, missing semi colons, …
-- **test** - when adding missing tests
-- **perf** - performance improvements
-- **revert** - rollback changes
-- **refactor** - reorganization without breaking changes and new features
+- `chore`: any repository maintainance changes
+- `feat`: code change that adds a new feature
+- `fix`: bug fix
+- `perf`: code change that improves performance
+- `refactor`: code change that is neither a feature addition nor a bug fix nor a performance improvement
+- `docs`: documentation only changes
+- `ci`: a change made to CI configurations and scripts
+- `style`: cosmetic code change
+- `test`: change that only adds or corrects tests
+- `revert`: change that reverts previous commits
 
 ### Allowed `<scope>`
 
-Directory name from `/packages/<scope>`
+Name of directory of a package (`/packages/<scope>`)
 
-### Style for `<description>`
+### `<description>` rules
 
-- only English language
-- Use imperative, present tense: `change` not `changed` nor `changes`
-- don't capitalize first letter
-- no dot (`.`) at the end
+- should be written in English
+- should be in imperative form (like `change` instead `changed` or `changes`)
+- should not be capitalized
+- should not have period at the end
 
-### Example commit messages
+### Commit message examples
 
 ```
 docs: fix typo in npm-react

tools/new-package-template/README.md

@@ -1,13 +1,15 @@
+{{description}}
+
 ## Installation
 
 ```sh
-npm i @reatom/<%= name %>
+npm install @reatom/{{name}}
 ```
 
 ## Usage
 
 ```ts
-import {} from '@reatom/<%= name %>'
+import {} from '@reatom/{{name}}'
 
 // ...
 ```

tools/new-package-template/package.json

@@ -1,9 +1,9 @@
 {
- "name": "@reatom/<%= name %>",
+ "name": null,
  "version": "3.5.0",
+ "description": null,
  "private": false,
  "sideEffects": false,
- "description": "Reatom for <%= name %>",
  "source": "src/index.ts",
  "exports": {
  "types": "./build/index.d.ts",
@@ -20,7 +20,6 @@
  "mangle": false
  },
  "scripts": {
- "sandbox": "vite",
  "prepublishOnly": "npm run build && npm run test",
  "build": "microbundle",
  "test": "ts-node src/index.test.ts",
@@ -29,24 +28,19 @@
  "dependencies": {
  "@reatom/core": ">=3.5.0"
  },
- "author": "artalar",
- "maintainers": [
- {
- "name": "artalar",
- "url": "https://github.com/artalar"
- }
- ],
+ "author": null,
+ "maintainers": null,
  "license": "MIT",
  "repository": {
  "type": "git",
- "url": "git+ssh://[email protected]/artalar/reatom.git"
+ "url": "git+ssh://[email protected]/artalar/reatom.git",
+ "directory": null
  },
  "bugs": {
  "url": "https://github.com/artalar/reatom/issues"
  },
- "homepage": "https://www.reatom.dev/package/<%= name %>",
+ "homepage": null,
  "keywords": [
- "<%= name %>",
  "reactive",
  "reactivity",
  "state-manager",

tools/new-package-template/src/index.test.ts

@@ -1,13 +1,12 @@
 import { test } from 'uvu'
 import * as assert from 'uvu/assert'
-
 import { createTestCtx } from '@reatom/testing'
+import {} from './index'
 
-import {} from './'
-
-test('base API', async () => {
+test('stub', () => {
  const ctx = createTestCtx()
- assert.ok(false, 'You forgot test you code')
+
+ assert.ok(false, 'No tests!')
 })
 
 test.run()

tools/new-package-template/src/index.ts

@@ -1,5 +1 @@
-import {} from '@reatom/core'
-
-export const <%= name %> = () => {
-
-}
+export {}