CONTRIBUTING.md

Contributing

Contributions to KeystoneJS in the form of issues and PRs are welcomed.

Contributions which improve the documentation and test coverage are particularly welcomed.

Community Ecosystem

Keystone makes no assumptions about type of applications it powers. It achieves flexibility through small, highly composable parts that allow you to build a foundation for a broad variety of applications.

For this reason we might not add features to Keystone if they are prescriptive about:

• Data structures
• Workflows
• Access controls
• Front-end application UI

But we want your contributions! We recognise many types of applications share common features and prescriptive patterns can sometimes be helpful, even at the expense of flexibility.

If you develop custom fields, adapters, apps or any other Keystone feature, (or have an idea) join us on the Keystone Slack channel or make a pull request to KeystoneJS-Contrib and we will add it to our list of community libraries.

Code of Conduct

KeystoneJS adheres to the Contributor Covenant Code of Conduct.

Repository Setup

KeystoneJS follows the Thinkmill Monorepo Style Guide. For more information on the reasoning behind using certain tooling, please refer to it.

Version management

Keystone uses @noviny's @changesets/cli to track package versions and publish packages. This tool allows each PR to indicate which packages need a version bump along with a changelog snippet. This information is then collated when performing a release to update package versions and CHANGELOG.md files.

What all contributors need to do

• Make your changes (as per usual)
• Before you make a Pull Request, run the yarn changeset command and answer the questions that are asked. It will want to know:
  • which packages you want to publish
  • what version you are releasing them at
  • a message to summarise the changes (this message will be written to the changelog of bumped packages)
• Before you accept the changeset, it will display all the data that will be written to the changeset. If this looks fine, agree, and a changeset will be generated in the .changeset directory.

After this, a new changeset will be added which is a markdown file with YAML front matter.

-| .changeset/
-|-| UNIQUE_ID.md

The message you typed can be found in the markdown file. If you want to expand on it, you can write as much markdown as you want, which will all be added to the changelog on publish. If you want to add more packages or change the bump types of any packages, that's also fine.

While not every changeset is going to need a huge amount of detail, a good idea of what should be in a changeset is:

• WHAT the change is
• WHY the change was made
• HOW a consumer should update their code

An example, if you generate a changeset that includes auth as a patch, and core as a minor, you can merge your PR, and the next time the version-packages command is run, these will both be updated.

---
'@keystone-6/auth': patch
'@keystone-6/core': minor
---

A very useful description of the changes should be here.

You can have multiple changesets in a single PR. This will give you more granular changelogs, and is encouraged.

Changeset guidelines

We’re sometimes lovingly picky on the wording of our changesets because these end up in changelogs that people like you read. We want to try to get a consistent tone of voice while providing useful information to the reader.

In particular, please try to write in the present tense, like git commits (e.g. "Adds a new feature" rather than "Added a new feature") and write in complete sentences. This means proper capitalisation and punctuation, including full stops/periods at the end of sentences. Changesets should be short, and prefer leaving complicated explanations to the pull request description.

How we version packages

Keystone follows the semver model of {major}.{minor}.{patch}. Version numbers are the first and most obvious way we have of communicating changes to our users, so it's important we convey consistent meaning with them, and strike a careful balance between releasing often vs. overloading consumers with package updates.

Generally, versions should be interpreted like:

• major means a breaking change to the public API of a package, and/or a meaningful change to the internal behaviour
• minor means we added a feature to the package, which is backwards compatible with the current major version
• patch means a bug has been fixed in the package

If a PR includes any of the above, it needs a changeset so the updated packages get released and versioned correctly.

Other reasons for versioning packages include:

• If a dependency is updated, and that dependency's API is exposed, the package exposing the API should be bumped by the same level as the dependency being updated. For example a new major version of mongoose would warrant a new major version of keystone.
• If a dependency is updated, and that dependency is not exposed, it may be important to release a package with the update, for example with security fixes. In that case, the package would be bumped with a patch version.

Versioning UI changes

Front-end packages (the Admin UI, Design System, etc) should always follow the rules above for API changes, but may also warrant a version bump for UI changes without an API change. This is more open to interpretation, but should follow the spirit of the rules above:

• major should be used if we're meaningfully changing how the UI looks or works (think: should we update screenshots on the website? might users need to relearn something they know how to do?)
• minor should be used if a new feature is available
• patch should be used if something has been tweaked or fixed

Versioning example projects

Since the example projects don't get published anywhere and don't expose API, it's less obvious when they should be versioned. In this case, think of "someone referring to the example project" as an API consumer, and use the version number to communicate anything they should know.

• major means the example has been meaningfully changed, and the difference would break expectations about how it works
• minor means the example has had features added or is significantly improved
• patch means something has been fixed

Minor refactoring, including incorporating changes to Keystone APIs, would not warrant updating the package version.

Generally, these guidelines are in place so that we don't spam consumers with version upgrades that don't provide value. They are subjective however, and not "one size fits all" so if you're not sure whether a change warrants a version bump, ask for advice in the PR.

Build Process

Some of the packages in keystone need to compiled before they're published, we use preconstruct to do this.

Preconstruct reads from the packages.json preconstruct field for configuration, in all we need to do is set the packages that we need to build. Preconstruct reads all of the packages specified in the packages and checks the main and module fields and generates compiled versions. Preconstruct under the hood uses rollup to bundle all of the modules together which means people can't expose and interact with the modules (e.g. to change internals that could change in a patch version). It also results in smaller builds because rollup is better at tree shaking than webpack. Preconstruct also uses babel and reads from the babel config in the repo to compile the code, there is one important babel plugin that Preconstruct adds which is @babel/plugin-transform-runtime which tells babel to import the helpers that it uses in generated code from a certain place rather than duplicating them in each package.

Preconstruct can generate a couple different types of modules, in keystone, we build esm and commonjs modules.

ESM bundles are built for newer bundlers like parcel, rollup and newer versions of webpack which understand ES modules and can build more optimised bundles from them than they can with commonjs.

We also build commonjs builds to run in node (for testing with jest or etc.) and for bundlers which don't understand esm. Preconstruct generates three files for commonjs, a production, development and a file to import those modules. The production one compiles out process.env.NODE_ENV !== 'production' checks which are common in front end libraries but process.env.NODE_ENV is expensive to check in node if it happens very often.