better docs all around (#85)

Author: Noviny

.changeset/thick-crabs-kneel/changes.json

@@ -0,0 +1 @@
+{ "releases": [{ "name": "extract-react-types-loader", "type": "patch" }], "dependents": [] }

.changeset/thick-crabs-kneel/changes.md

@@ -0,0 +1 @@
+Add readme

code-of-conduct.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at `[email protected]`. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

contributing.md

@@ -0,0 +1,93 @@
+Contributions to Extract React Types in the form of issues and PRs are welcomed.
+
+## Code of Conduct
+
+Extract React Types adheres to the [Contributor Covenant Code of Conduct](code-of-conduct.md).
+
+## Version management
+
+Keystone uses @noviny's [@changesets/cli](https://github.com/atlassian/changesets) in combination with `bolt` 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 `bolt 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 inform you of any other dependent packages within the repo that will also be bumped by this changeset. If this looks fine, agree, and a changeset will be generated in the `.changeset` directory.
+
+Each changeset contains two files; `changes.json`, which contains structured data which indicates the packages which need to be updated, and `changes.md`, which contains a markdown snippet which will be included in the `CHANGELOG.md` files for the updated packages.
+
+Here is what a `changeset.json` looks like:
+
+```
+{
+  "releases": [
+    { "name": "@keystone-alpha/adapter-mongoose", "type": "patch" },
+    { "name": "@keystone-alpha/keystone", "type": "minor" }
+  ],
+  "dependents": []
+}
+```
+
+You can have multiple changesets in a single PR. This will give you more granular changelogs, and is encouraged.
+
+## Release Guidelines
+
+## Publishing
+
+### How to do a release
+
+> This should only ever be done by a very short list of core contributors
+
+Releasing is a two-step process. The first step updates the packages, and the second step publishes updated packages to npm.
+
+#### Steps to version packages
+
+The first step is `bolt apply-changesets`. This will find all changesets that have been created since the last release, and update the version in package.json as specified in those changesets, flattening out multiple bumps to a single package into a single version update.
+
+The `bolt release` command will release new versions of packages to npm.
+
+The commands to run are:
+
+```sh
+git checkout master
+git pull
+git branch -D temp-release-branch
+git checkout -b temp-release-branch
+bolt apply-changesets
+git add .
+git commit -m "Run version-packages"
+git push --set-upstream origin temp-release-branch
+```
+
+Once you have run this you will need to make a pull request to merge this back into master.
+
+#### Release Process
+
+Once the version changes are merged back in to master, to do a manual release:
+
+```sh
+git checkout master
+git pull
+bolt
+bolt release
+git push --tags
+bolt
+```
+
+The `bolt publish-changed` command finds packages where the version listed in the `package.json` is ahead of the version published on npm, and attempts to publish just those packages.
+
+Because of this, we should keep the following in mind:
+
+- Once the `apply-changesets` command has been run, the PR from the `temp-release-branch` should be merged before any other PRs are merged into master, to ensure that no changesets are skipped from being included in a release.
+- There is no reason you should ever manually edit the version in the `package.json`
+
+### A quick note on changelogs
+
+The release process will automatically generate and update a `CHANGELOG.md` file, however this does not need to be the only way this file is modified. The changelogs are deliberately static assets so past changelogs can be updated or expanded upon.
+
+In addition, content added above the last released version will automatically be appended to the next release. If your changes do not fit comfortably within the summary of a changelog, we encourage you to add a more detailed account directly into the `CHANGELOG.md`.

package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "test": "jest",
     "changeset": "changeset",
-    "bump": "changeset bump",
+    "apply-changesets": "changeset bump",
     "release": "yarn build && changeset release --public",
     "postinstall": "preconstruct dev",
     "dev:pretty-proptypes": "bolt w pretty-proptypes run dev",

packages/extract-react-types-loader/README.md

@@ -0,0 +1,3 @@
+# Extract React Types Loader
+
+Please see [the documentation for pretty-proptypes](https://github.com/atlassian/extract-react-types/tree/master/packages/pretty-proptypes) for information on how to use this package.

readme.md

@@ -11,4 +11,4 @@ Packages:
 
 ## Contribute
 
-Pull requests, issues and comments welcome
+Pull requests, issues and comments welcome - please read our [contributing guidelines](./contributing.md) and our [code of conduct](./code-of-conduct.md).