docs: rework readme (#1017)

Co-authored-by: ST-DDT <[email protected]>
Co-authored-by: Eric Cheng <[email protected]>
Co-authored-by: pkuczynski <[email protected]>

1 files changed, 54 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 65e70c47..b840ac80 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,3 +20,57 @@ If you want to make `Faker` a better, please read the following contribution gui
 The sources are located in the [src](src) directory.
 All fake data generators are divided into namespaces (each namespace being a separate module).
 Most of the generators use the _definitions_, which are just plain JavaScript objects/arrays/strings that are separate for each [locale](src/locales).
+
+## Building Faker
+
+The project is being built by [esbuild](https://esbuild.github.io) (see [bundle.ts](scripts/bundle.ts))
+
+```shell
+pnpm install
+pnpm run build
+```
+
+## Testing
+
+Before you can run the tests, you need to install all dependencies and build the project, because some tests depend on the bundled content.
+
+```shell
+pnpm install
+pnpm run build
+
+pnpm run test
+# or
+pnpm run coverage
+```
+
+You can view a generated code coverage report at `coverage/index.html`.
+
+## Adding new locale or updating existing one
+
+After adding new or updating existing locale data, you need to run `pnpm run generate:locales` to generate/update the related files.
+
+## Developing the docs
+
+Before running the docs, build the Faker dist, it's used inside of certain routes.
+
+```shell
+pnpm run build
+
+pnpm run docs:dev
+```
+
+## Building and serving the docs statically
+
+If you changed something heavily in the docs, like auto-generating content, you should check the docs statically, because it could differ from the dev version.
+Before running the docs, build the Faker dist, it's used inside of certain routes.
+
+```shell
+pnpm run build
+
+pnpm run docs:build # Output docs to /dist
+pnpm run docs:serve # Serve docs from /dist
+```
+
+## Deploying documentation
+
+See the [netlify.toml](netlify.toml) for configuration.