Skip to content

Latest commit

 

History

History
256 lines (174 loc) · 7.66 KB

CONTRIBUTING.md

File metadata and controls

256 lines (174 loc) · 7.66 KB

CONTRIBUTING

Contributions are always welcome, no matter how large or small. Before contributing, please read the code of conduct.

For details on contributing to documentation, see Website Readme.

Setup

Install Node.js (LTS) on your system.

Install dependencies

git clone https://github.com/decaporg/decap-cms
cd decap-cms
npm install

Run locally

npm run start

Available scripts

clean

Removes all of the CMS package dist directories.

npm run clean

reset

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

npm run reset

build

Runs the clean script and builds the CMS packages.

npm run build

build-preview

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

npm run build-preview

test

Runs linting and Jest tests.

npm run test

test:all

Runs linting, Jest, and Cypress tests.

npm run test:all

test:e2e

Runs Cypress e2e tests.

npm run test:e2e

test:e2e:dev

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

npm run test:e2e:dev

format

Formats code and docs according to our style guidelines.

npm run format

Pull Requests

We actively welcome your pull requests!

If you need help with Git or our workflow, please ask in our community chat. We want your contributions even if you're just learning Git. Our maintainers are happy to help!

Decap CMS uses the Forking Workflow + Feature Branches. Additionally, PR's should be rebased on main when opened, and again before merging.

  1. Fork the repo.
  2. Create a branch from main. 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 npm run test and ensure the test suite passes.
  6. Use npm run 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

npm run 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.
backend:
  name: github
  repo: owner-name/repo-name
  1. Change the content of dev-test/index.html to:
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Decap CMS</title>
  </head>
  <body>
    <script src="dist/decap-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 Decap 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.

  1. Run npm run start
  2. 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 and Netlify Identity enabled. An easy way to create such a site is to use a template, for example the Gatsby template

  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

Fine tune the way you run unit tests

There are situations where you would want to run a specific test file, or tests that match a certain pattern.

To run all the tests for a specific file, use this command:

npx jest <filename or file path>

The first part of the command, npx jest means running the locally installed version of jest. It is equivalent to running node_modules/.bin/jest.

Example for running all the tests for the file gitlab.spec.js: npx jest gitlab.spec.js

Some test files like API.spec.js is available in several packages. You can pass a regexp pattern instead of file path to narrow down files.

Example for running all the tests for the file API.spec.js in the decap-cms-backend-gitlab package:

npx jest ".+backend-gitlab/.+/API.spec.js

To run a specific test in a file, add the flag --testNamePattern, or -t for short followed by a regexp to match your test name.

Example for running the test "should return true on project access_level >= 30" in the API.spec.js in decap-cms-backend-gitlab package:

npx jest -t "true on p" ".+backend-gitlab/.+/API.spec.js"

For more information about running tests exactly the way you want, check out the official documentation for Jest CLI.

Releasing

Decap CMS uses NPM trusted publishers with OIDC for secure, automated package publishing.

How It Works

  • Publishing is automated via GitHub Actions when version tags are pushed
  • Uses OpenID Connect (OIDC) for authentication. No NPM tokens required
  • Each package has a trusted publisher configured on npmjs.com
  • Workflow generates short-lived, cryptographically-signed tokens automatically
  • Publishes all changed packages in the monorepo via Lerna

Release Process

  1. Prepare the release:
# Ensure your local `main` branch is up to date
npm prune
npm install
npm run test

# Bump versions for changed packages
npx lerna version

# This will:
# - Detect changed packages since last release
# - Bump versions according to conventional commits
# - Update CHANGELOG.md
# - Create git commit and tags
# - Push to upstream

  1. Automated publishing:

    • Tags pushed to main trigger the publish workflow automatically
    • GitHub Actions runs tests and builds packages
    • Lerna publishes changed packages to npm using OIDC
    • Provenance attestations are generated automatically

  2. Create GitHub release:

    • Go to Releases
    • Draft a new release from the tag
    • Add release notes highlighting changes

Manual Publishing (Emergency Only)

If automated publishing fails and you need to publish manually:

# Authenticate with npm (uses session-based auth with 2FA)
npm login

# Publish changed packages
npm run lerna:publish

Note: Manual publishing still requires 2FA. Use recovery codes if you don't have access to your 2FA device.

License

By contributing to Decap CMS, you agree that your contributions will be licensed under its MIT license.