forked from sunnymoon/keystone
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Simplify README.md and CONTRIBUTING.md (keystonejs#8587)
Co-authored-by: Daniel Cousens <[email protected]>
- Loading branch information
Showing
2 changed files
with
16 additions
and
124 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,129 +1,26 @@ | ||
| # Contributing | ||
|
|
||
| Contributions to KeystoneJS in the form of issues and PRs are welcomed. | ||
| Contributions to Keystone the form of issues and pull requests 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. | ||
| Keystone doesn't make too many assumptions about the types of applications it can support. | ||
| We are building a targeted programming interface for designing and iterating on domain models and schemas, resulting in a web application framework that is powered by Typescript and GraphQL. | ||
|
|
||
| For this reason we might not add features to Keystone if they are prescriptive about: | ||
| We value your ideas and contributions! | ||
| If you're interested, [open a discussion](https://github.com/keystonejs/keystone/discussions/new/choose) or [open a pull request](https://github.com/keystonejs/keystone/pulls) and start the conversation! | ||
| Community contributions are the driving force that makes our community ecosystem thrive. | ||
|
|
||
| - Data structures | ||
| - Workflows | ||
| - Access controls | ||
| - Front-end application UI | ||
| ## Versioning | ||
|
|
||
| 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](https://community.keystonejs.com) or make a pull request to [KeystoneJS-Contrib](https://github.com/keystonejs-contrib/keystonejs-contrib) and we will add it to our list of community libraries. | ||
| Keystone follows [semver](https://semver.org/). | ||
|
|
||
| ## Code of Conduct | ||
|
|
||
| KeystoneJS adheres to the [Contributor Covenant Code of Conduct](/CODE-OF-CONDUCT.md). | ||
|
|
||
| ## Repository Setup | ||
|
|
||
| KeystoneJS follows the [Thinkmill Monorepo Style Guide](https://github.com/Thinkmill/monorepo). | ||
| For more information on the reasoning behind using certain tooling, please refer to it. | ||
|
|
||
| ### Version management | ||
|
|
||
| Keystone uses @noviny's [@changesets/cli](https://github.com/changesets/changesets) 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 `pnpm 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. | ||
|
|
||
| ```md | ||
| --- | ||
| '@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](https://github.com/preconstruct/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. | ||
| Keystone adheres to the [Contributor Covenant Code of Conduct](/CODE-OF-CONDUCT.md). | ||
|
|
||
| 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. | ||
| ## Security | ||
|
|
||
| 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. | ||
| For vulnerability reporting, please refer to our [security policy](/SECURITY.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters