From 5e4e23548288f9cefa4f5d32dc0fda06685a5a39 Mon Sep 17 00:00:00 2001 From: Luccas Mateus de Medeiros Gomes Date: Wed, 12 Apr 2023 12:58:25 -0300 Subject: [PATCH] [docs][sm] - add start of contributing docs --- CONTRIBUTING.md | 176 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ab256256 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,176 @@ +--- +title: Developer docs for contributors +--- + +## Our repository + +https://github.com/datopian/portaljs + +Structure: + +- **examples** + - **ckan**: Example utilizing CKAN as a backend + - **dataset-frictionless**: Example utilizing a frictionless dataset as an example +- **site**: the website for the project, with a landing page and the docs +- **packages**: + - **portaljs-components**: the library of components for creating a data portal + +## How to contribute + +You can start by checking our [issues board](https://github.com/datopian/portaljs/issues). + +If you'd like to work on one of the issues you can: + +1. Comment on the issue to let us know you'd like to work on, so that we can assist you and to make sure no one has started looking into it yet. +2. If good to go, fork the main repository. +3. Clone the forked repository to your machine. +4. Create a feature branch (e.g. `50-update-readme`, where `50` is the number of the related issue). +5. Commit your changes to the feature branch. +6. Push the feature branch to your forked repository. +7. Create a Pull Request against the original repository. + - add a short description of the changes included in the PR +8. Address review comments if requested by our demanding reviewers 😜. + +If you have an idea for improvement, and it doesn't have a corresponding issue yet, simply submit a new one. + +> [!note] +> Join our [Discord channel](https://discord.gg/rTxfCutu) do discuss existing issues and to ask for help. + +## Nx + +Our monorepo is set up with Nx build system. See their [official documentation](https://nx.dev/getting-started) to learn more. + +### Tasks + +Each project(stuff inside either the packages or examples folder) within this repository has a `project.json` file, which defines all targets that can be run on this project. + +A target is an action that can be taken on a project. +A task is a single target run on a given project. + +#### Running single tasks + +To run a single target on a given project run: + +```sh +npx nx +# e.g. npx nx serve ckan +``` + +or you can use just: + +```sh +nx +# e.g. npx nx serve ckan +``` +if you have the `nx` binary installed globally in your machine + +#### Running multiple tasks + +To run a given target on all projects that define it, run: + +```sh +npx nx run-many --target= +# e.g. npx nx run-many --target=serve +``` + +#### Running tasks affected by your changes + +When you run `nx affected --target=`, Nx looks at the files you changed (compares current HEAD vs base), and it uses this to figure out the list of projects in the workspace that may be affected by this change. It then runs the run-many command with that list. + +```sh +npx nx affected --target= +# e.g. npx nx affected --target=serve + +# or +# npx nx affected: +# e.g. npx nx affected:serve +``` + +> To learn more about how Affected works, read [this Nx docs page](https://nx.dev/concepts/affected#how-affected-works). + +### Linting and formatting + +Nx uses eslint for code linting and prettier for code formatting. There is a base `eslintrc.json` file in the root of this repository that defines global eslint configs. Each project can have its own `eslintrc.json` for project-specific eslint confiurations. + +To lint the code in a single project: + +```sh +npx nx lint +# npx nx lint ckan +``` + +To lint all projects: + +``` +npx nx run-many --target=lint +``` + +To check code formatting in selected projects: + +```sh +npx nx format:check --projects= +# npx nx format:check --projects=ckan,dataset-frictionless +``` + +To check code formatting in all projects: + +```sh +npx nx format:check --all +# or +# npx nx format +``` + +To fix code formatting in selected projects: + +```sh +npx nx format:write --projects= +# npx nx format:write --projects=ckan,dataset-frictionless +``` + +To fix formatting in all projects: + +```sh +npx nx format --all +# or +# npx nx format:write --all +``` + +> To learn more about all the available options for the format command, see [format:check](https://nx.dev/nx/format-check) and [format:write](https://nx.dev/nx/format-write) docs pages. + +### Creating a library + +To create a new publishable js library: + +```sh +nx g @nrwl/next:lib --js --publishable --importPath @portaljs/ +``` + +### Creating an example + +To create a new next.js app in the examples folder : + +```sh +nx g @nrwl/next:app +``` + +### Dependency graph + +To see the graph of dependencies between the projects within this repository, run: + +```sh +npx nx graph +``` + +### Caching + +Nx by default uses local computation cache to store results of the tasks it has run. + +### Configuration + +The entry point of Nx's confiuration is the `nx.json` file in the root of this repository. It defines global configurations as well default configurations for projects targets. + +To learn more see this [offical docs page](https://nx.dev/reference/nx-json). + +Each project also has it's own configuration file - `project.json`, where you can define and configure it's targets (and more). + +To learn more see this [offical docs page](https://nx.dev/reference/project-configuration).