Skip to content

Latest commit

聽

History

History
198 lines (129 loc) 路 5.88 KB

CONTRIBUTING.md

File metadata and controls

198 lines (129 loc) 路 5.88 KB
Raw
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.

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. Add changeset file describing the changes. (See section below)
  7. Push the feature branch to your forked repository.
  8. Create a Pull Request against the original repository.
    • add a short description of the changes included in the PR
  9. 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 do discuss existing issues and to ask for help.

Nx

Our monorepo is set up with Nx build system. See their official documentation 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:

npx nx <target> <project>
# e.g. npx nx serve ckan

or you can use just:

nx <target> <project>
# 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:

npx nx run-many --target=<target>
# e.g. npx nx run-many --target=serve

Running tasks affected by your changes

When you run nx affected --target=<some-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.

npx nx affected --target=<target>
# e.g. npx nx affected --target=serve

# or
# npx nx affected:<target>
# e.g. npx nx affected:serve

To learn more about how Affected works, read this Nx docs page.

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:

npx nx lint <project>
# npx nx lint ckan

To lint all projects:

npx nx run-many --target=lint

To check code formatting in selected projects:

npx nx format:check --projects=<array of projects>
# npx nx format:check --projects=ckan,dataset-frictionless

To check code formatting in all projects:

npx nx format:check --all
# or
# npx nx format

To fix code formatting in selected projects:

npx nx format:write --projects=<array projects>
# npx nx format:write --projects=ckan,dataset-frictionless

To fix formatting in all projects:

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 and format:write docs pages.

Creating a library

To create a new publishable js library:

nx g @nrwl/next:lib --js --publishable --importPath @portaljs/<library-name>

Creating an example

To create a new next.js app in the examples folder :

nx g @nrwl/next:app <example-name>

Dependency graph

To see the graph of dependencies between the projects within this repository, run:

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.

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.

Changesets and publishing packages

This monorepo is set up with changesets versioning tool. See their github repository to learn more.

What are Changesets?

Changesets are files that describe the intention of a contributor to bump a version of the package according to their changes. Changeset file holds two key bits of information: a version type (following semver), and change information to be added to a changelog.

Adding changesets

In the root directory of the repo, run:

npx changeset

Select the package that has been changed, the semver version that should be bumped with it and a description of your changes. Please make sure to add the most accurate but also concise information.

To learn about semantic versioning standards see this semver doc page.