Contributing

If you wish to contribute to the widget-editor, please have a read at this guide that goes through the installation of the code, setting up of your environment and the use of the playground.

Table of content

• Installation
• Setting up your environment
• Adding dependencies
• Playground
• Deployment

Installation

The first thing that you'll need to do is to clone the repository:

git clone https://github.com/Vizzuality/widget-editor.git

Then, you will need to install the dependencies:

cd widget-editor
yarn

You will also need to build the project initially so all the packages can have access to each other:

yarn build

Finally, you can run the watch mode and open the playground by executing the following:

yarn start:widget-editor

The command will automatically open a new tab in your browser. You can also manually open http://localhost:3000/. If the tab appears empty, reload the page.

Setting up your environment

Before making any changes to the widget-editor, we'd suggest you follow these recommendations to properly set up your environment:

• Install NVM to manage your different Node.js versions and execute nvm use at the root of the folder to use the correct one
• Use Visual Studio Code as a text editor to benefit from automatic type checking
• Configure your text editor with the Prettier, ESLint and EditorConfig plugins

Adding dependencies

Because the repository is managed as a monorepo, there is a special way to add dependencies to one of the packages. To do so, run the following command:

yarn workspace @widget-editor/{package} add {dependency}

You would do the same to remove depencies (replacing add by remove).

We do not recommend adding dependencies globally unless of it is for development. In such a case, run:

yarn add {dependency} --dev -W

Playground

The playground is the place where the widget-editor is tested in isolation. It's a simple React app that has settings that directly interface with the editor to modify its behavior.

There you can see its internal state, inspect its Redux state via a browser extension such as Redux DevTools and toggle some of its settings.

Whenever a bug report is made to the widget-editor, it is a good practice to test it in the playground to make sure the bug does not come from other parts of the host app.

The playground is also available online at this URL: https://vizzuality.github.io/widget-editor/

Deployment

Once several changes have been made to the widget-editor and they've all been reviewed by someone else, it might be time to release a new version of the editor.

To do so, follow these steps:

1. Check the notify-release tag on GitHub. PRs marked with it may contain important or breaking changes that are worth mentioning in the changelog.
2. Create a release note with the correct version number in the changelog file. It is shared with clients and developers working with the editor.
3. Checkout main and pull in develop. Anything that is in the develop branch is considered production-ready.
4. Run yarn deploy. This will ask you what version you want to release: major, minor or patch. You need to have access to our NPM organization to do so.
5. After the release of the editor, you can deploy the playground by running yarn deploy:playground.
6. If you have access to our Slack workspace, notify the team about the deployments in #widget-editor-dev.