static-cms/CONTRIBUTING.md

# CONTRIBUTING

Contributions are always welcome, no matter how large or small. Before contributing,
please read the [code of conduct](CODE_OF_CONDUCT.md).

For details on contributing to documentation, see [Website Directory Readme](https://github.com/netlify/netlify-cms/blob/master/website/README.md).

## Setup

> Install [Node.js (LTS)](https://nodejs.org/) and [yarn](https://yarnpkg.com/en/docs/install) on your system.

### Install dependencies

> Only required on the first run, subsequent runs can use `yarn start` to both bootstrap and run the development server.

```sh
git clone https://github.com/netlify/netlify-cms
cd netlify-cms
yarn
yarn bootstrap
```

### Run locally

```sh
yarn start
```

## Available scripts

### bootstrap

Bootstraps the monorepo.

```sh
yarn bootstrap
```

### watch

Watches all CMS packages and transpiles them on change.

```sh
yarn watch
```

### start

Starts the development server. This task runs both the `bootstrap` and `watch` scripts.

```sh
yarn start
```

### clean

Removes all of the CMS package `dist` directories.

```sh
yarn clean
```

### reset

Runs the `clean` script and removes all the `node_modules` from the CMS packages.

```sh
yarn reset
```

### build

Runs the `clean` script and builds the CMS packages.

```sh
yarn build
```

### build-preview

Runs the `build` and `build-preview` scripts in each package and serves the resulting build locally.

```sh
yarn build-preview
```

### test

Runs linting and Jest tests.

```sh
yarn test
```

### test:all

Runs linting, Jest, and Cypress tests.

```sh
yarn test:all
```

### test:e2e

Runs Cypress e2e tests.

```sh
yarn test:e2e
```

### test:e2e:dev

Runs Cypress e2e tests on watch mode with an open instance of Chrome.

```sh
yarn test:e2e:dev
```

### format

Formats code and docs according to our style guidelines.

```sh
yarn format
```

## Pull Requests

We actively welcome your pull requests!

If you need help with Git or our workflow, please ask in our [community chat](https://netlifycms.org/chat). We want your contributions even if you're just learning Git. Our maintainers are happy to help!

Netlify CMS uses the [Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow) + [Feature Branches](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). Additionally, PR's should be [rebased](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) on master when opened, and again before merging.

1. Fork the repo.
2. Create a branch from `master`. If you're addressing a specific issue, prefix your branch name with the issue number.
3. If you've added code that should be tested, add tests.
4. If you've changed APIs, update the documentation.
5. Run `yarn test` and ensure the test suite passes.
6. Use `yarn format` to format and lint your code.
7. PR's must be rebased before merge (feel free to ask for help).
8. PR should be reviewed by two maintainers prior to merging.

## Debugging

`yarn start` spawns a development server and uses `dev-test/config.yml` and `dev-test/index.html` to serve the CMS.
In order to debug a specific issue follow the next steps:

1. Replace `dev-test/config.yml` with the relevant `config.yml`. If you want to test the backend, make sure that the `backend` property of the config indicates which backend you use (Github, Gitlab, Bitbucket etc) and path to the repo.

```js
backend:
  name: github
  repo: owner-name/repo-name
```

2. Change the content of `dev-test/index.html` to:

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Netlify CMS</title>
  </head>
  <body>
    <script src="dist/netlify-cms.js"></script>
    <!-- <script>
      // this is the place to add CMS customizations if you need to, e.g.
      CMS.registerPreviewTemplate('posts', PostPreview);
    </script> -->
  </body>
</html>
```
The most important thing is to make sure that Netlify CMS is loaded from the `dist` folder. This way, every time you make changes to the source code, they will be compiled and reflected immediately on `localhost`.

3. Run `yarn start`
4. Open `http://localhost:8080/` in the browser and you should have access to the CMS

### Debugging Git Gateway

When debugging the CMS with Git Gateway you must:

1. Have a Netlify site with [Git Gateway](https://docs.netlify.com/visitor-access/git-gateway/) and [Netlify Identity](https://docs.netlify.com/visitor-access/identity/) enabled. An easy way to create such a site is to use a [template](https://www.netlifycms.org/docs/start-with-a-template/), for example the [Gatsby template](https://app.netlify.com/start/deploy?repository=https://github.com/AustinGreen/gatsby-starter-netlify-cms&stack=cms)
2. Tell the CMS the URL of your Netlify site using a local storage item. To do so:

    1. Open `http://localhost:8080/` in the browser
    2. Open the Developer Console. Write the below command and press enter: `localStorage.setItem('netlifySiteURL', 'https://yourwebsiteurl.netlify.app/')`
    3. To be sure, you can run this command as well: `localStorage.getItem('netlifySiteURL')`
    4. Refresh the page
    5. You should be able to log in via your Netlify Identity email/password

## License

By contributing to Netlify CMS, you agree that your contributions will be licensed
under its [MIT license](LICENSE).
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			`# CONTRIBUTING`

			`Contributions are always welcome, no matter how large or small. Before contributing,`
			`please read the [code of conduct](CODE_OF_CONDUCT.md).`

Issue 1038 (#1631) * Added note to CONTRIBUTING intro with link to documentation contribution guide (/website/readme.md) * Added cory-wc to contributors 2018-08-20 16:54:24 -04:00			`For details on contributing to documentation, see [Website Directory Readme](https://github.com/netlify/netlify-cms/blob/master/website/README.md).`

Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			`## Setup`

feat(docs): add a Debugging section to CONTRIBUTING.md (#4575) 2020-12-06 17:56:31 +01:00			`> Install [Node.js (LTS)](https://nodejs.org/) and [yarn](https://yarnpkg.com/en/docs/install) on your system.`
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00
Update contributing doc to better handle first run dpendency requirements (#1645) The command `yarn start` is dependent on the `npm-run-all` package, therefore we can't recommend this as the first command someone runs after they just clone the repository in case they don't have it globally installed. Trying to `yarn start` without this package gets: ``` /bin/sh: run-s: command not found error Command failed with exit code 127. info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command. ``` Therefore, on first setup it is recommended to run `yarn bootstrap` as the first command. 2018-08-23 03:02:53 +10:00			`### Install dependencies`

feat(docs): add a Debugging section to CONTRIBUTING.md (#4575) 2020-12-06 17:56:31 +01:00			> Only required on the first run, subsequent runs can use `yarn start` to both bootstrap and run the development server.
Update contributing doc to better handle first run dpendency requirements (#1645) The command `yarn start` is dependent on the `npm-run-all` package, therefore we can't recommend this as the first command someone runs after they just clone the repository in case they don't have it globally installed. Trying to `yarn start` without this package gets: ``` /bin/sh: run-s: command not found error Command failed with exit code 127. info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command. ``` Therefore, on first setup it is recommended to run `yarn bootstrap` as the first command. 2018-08-23 03:02:53 +10:00
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```sh
feat(docs): add a Debugging section to CONTRIBUTING.md (#4575) 2020-12-06 17:56:31 +01:00			`git clone https://github.com/netlify/netlify-cms`
			`cd netlify-cms`
			`yarn`
			`yarn bootstrap`
Update contributing doc to better handle first run dpendency requirements (#1645) The command `yarn start` is dependent on the `npm-run-all` package, therefore we can't recommend this as the first command someone runs after they just clone the repository in case they don't have it globally installed. Trying to `yarn start` without this package gets: ``` /bin/sh: run-s: command not found error Command failed with exit code 127. info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command. ``` Therefore, on first setup it is recommended to run `yarn bootstrap` as the first command. 2018-08-23 03:02:53 +10:00			```

			`### Run locally`

			```sh
docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`yarn start`
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```

docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00			`## Available scripts`

docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`### bootstrap`
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00
chore: update prerelease scripts 2019-03-21 12:12:16 -04:00			`Bootstraps the monorepo.`
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```sh
docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`yarn bootstrap`
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```

docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`### watch`
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00
			`Watches all CMS packages and transpiles them on change.`

Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```sh
docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`yarn watch`
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```
build: fix windows build, build on multiple os using node 12 only (#3449) 2020-03-23 14:57:18 +02:00
docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`### start`
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00
			Starts the development server. This task runs both the `bootstrap` and `watch` scripts.

Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```sh
docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`yarn start`
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```

docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`### clean`
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00
			Removes all of the CMS package `dist` directories.

Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```sh
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00			`yarn clean`
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```

docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`### reset`
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00
			Runs the `clean` script and removes all the `node_modules` from the CMS packages.

			```sh
			`yarn reset`
			```

docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`### build`
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00
			Runs the `clean` script and builds the CMS packages.

			```sh
			`yarn build`
			```

docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`### build-preview`
chore: add build-preview task for local build testing (#1539) 2018-07-28 17:26:47 -04:00
			Runs the `build` and `build-preview` scripts in each package and serves the resulting build locally.

			```sh
			`yarn build-preview`
			```

docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`### test`
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00
docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`Runs linting and Jest tests.`
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00
			```sh
docs: update contributor docs to reflect lerna (#1523) 2018-07-27 09:05:51 -06:00			`yarn test`
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			```

docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`### test:all`
chore: add code formatting and linting (#952) 2018-08-07 14:46:54 -06:00
docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`Runs linting, Jest, and Cypress tests.`

			```sh
			`yarn test:all`
			```

			`### test:e2e`

			`Runs Cypress e2e tests.`

			```sh
			`yarn test:e2e`
			```

			`### test:e2e:dev`
chore: add code formatting and linting (#952) 2018-08-07 14:46:54 -06:00
docs: add a few more test commands to CONTRIBUTING.md (#2871) 2019-11-12 15:38:28 -05:00			`Runs Cypress e2e tests on watch mode with an open instance of Chrome.`

			```sh
			`yarn test:e2e:dev`
			```

			`### format`

			`Formats code and docs according to our style guidelines.`
chore: add code formatting and linting (#952) 2018-08-07 14:46:54 -06:00
			```sh
			`yarn format`
			```

Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			`## Pull Requests`

docs: add Git details to CONTRIBUTING.md (#1663) 2018-08-27 14:04:11 -06:00			`We actively welcome your pull requests!`
Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00
chore: switch chat links to slack (#2782) 2019-10-22 20:59:04 -04:00			`If you need help with Git or our workflow, please ask in our [community chat](https://netlifycms.org/chat). We want your contributions even if you're just learning Git. Our maintainers are happy to help!`
docs: add Git details to CONTRIBUTING.md (#1663) 2018-08-27 14:04:11 -06:00
Update CONTRIBUTING.md (#1805) Fixed broken links. 2018-10-10 20:37:49 -03:00			`Netlify CMS uses the [Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow) + [Feature Branches](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). Additionally, PR's should be [rebased](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) on master when opened, and again before merging.`
docs: add Git details to CONTRIBUTING.md (#1663) 2018-08-27 14:04:11 -06:00
			`1. Fork the repo.`
			2. Create a branch from `master`. If you're addressing a specific issue, prefix your branch name with the issue number.
build: fix windows build, build on multiple os using node 12 only (#3449) 2020-03-23 14:57:18 +02:00			`3. If you've added code that should be tested, add tests.`
			`4. If you've changed APIs, update the documentation.`
			5. Run `yarn test` and ensure the test suite passes.
			6. Use `yarn format` to format and lint your code.
			`7. PR's must be rebased before merge (feel free to ask for help).`
			`8. PR should be reviewed by two maintainers prior to merging.`
Docs: Add yourself as a contributor (#677) 2017-10-12 00:15:04 +02:00
feat(docs): add a Debugging section to CONTRIBUTING.md (#4575) 2020-12-06 17:56:31 +01:00			`## Debugging`

			`yarn start` spawns a development server and uses `dev-test/config.yml` and `dev-test/index.html` to serve the CMS.
			`In order to debug a specific issue follow the next steps:`

Add more details to Debugging section (#5814) - Add more concrete instruction for configuring backend - Explain what users should look for when changing `dev-test/index.html` - Add more info to use local storage to set Netlify site's URL 2021-09-29 18:34:29 +07:00			1. Replace `dev-test/config.yml` with the relevant `config.yml`. If you want to test the backend, make sure that the `backend` property of the config indicates which backend you use (Github, Gitlab, Bitbucket etc) and path to the repo.

			```js
			`backend:`
			`name: github`
			`repo: owner-name/repo-name`
			```
feat(docs): add a Debugging section to CONTRIBUTING.md (#4575) 2020-12-06 17:56:31 +01:00
			2. Change the content of `dev-test/index.html` to:

			```html
			`<!DOCTYPE html>`
			`<html>`
			`<head>`
			`<meta charset="utf-8" />`
			`<title>Netlify CMS</title>`
			`</head>`
			`<body>`
			`<script src="dist/netlify-cms.js"></script>`
			`<!-- <script>`
			`// this is the place to add CMS customizations if you need to, e.g.`
			`CMS.registerPreviewTemplate('posts', PostPreview);`
			`</script> -->`
			`</body>`
			`</html>`
			```
Add more details to Debugging section (#5814) - Add more concrete instruction for configuring backend - Explain what users should look for when changing `dev-test/index.html` - Add more info to use local storage to set Netlify site's URL 2021-09-29 18:34:29 +07:00			The most important thing is to make sure that Netlify CMS is loaded from the `dist` folder. This way, every time you make changes to the source code, they will be compiled and reflected immediately on `localhost`.
feat(docs): add a Debugging section to CONTRIBUTING.md (#4575) 2020-12-06 17:56:31 +01:00
			3. Run `yarn start`
			4. Open `http://localhost:8080/` in the browser and you should have access to the CMS

			`### Debugging Git Gateway`

			`When debugging the CMS with Git Gateway you must:`

			`1. Have a Netlify site with [Git Gateway](https://docs.netlify.com/visitor-access/git-gateway/) and [Netlify Identity](https://docs.netlify.com/visitor-access/identity/) enabled. An easy way to create such a site is to use a [template](https://www.netlifycms.org/docs/start-with-a-template/), for example the [Gatsby template](https://app.netlify.com/start/deploy?repository=https://github.com/AustinGreen/gatsby-starter-netlify-cms&stack=cms)`
			`2. Tell the CMS the URL of your Netlify site using a local storage item. To do so:`

			1. Open `http://localhost:8080/` in the browser
Add more details to Debugging section (#5814) - Add more concrete instruction for configuring backend - Explain what users should look for when changing `dev-test/index.html` - Add more info to use local storage to set Netlify site's URL 2021-09-29 18:34:29 +07:00			2. Open the Developer Console. Write the below command and press enter: `localStorage.setItem('netlifySiteURL', 'https://yourwebsiteurl.netlify.app/')`
feat(docs): add a Debugging section to CONTRIBUTING.md (#4575) 2020-12-06 17:56:31 +01:00			3. To be sure, you can run this command as well: `localStorage.getItem('netlifySiteURL')`
			`4. Refresh the page`
			`5. You should be able to log in via your Netlify Identity email/password`

Add OSS management files. (#130) Inspired by Docker and Yarn. We can add more things later if we need them, but I think this is a good start. Signed-off-by: David Calavera <david.calavera@gmail.com> 2016-10-21 15:36:14 -07:00			`## License`

			`By contributing to Netlify CMS, you agree that your contributions will be licensed`
			`under its [MIT license](LICENSE).`