docs(*) contribution, pr, and style guide - INTF-944 (#55)

Aron Eidelman · web-flow · commit 56c3ad85c061 · 2019-01-18T10:40:16.000-08:00
Add guidelines for creating a new Kongponent from start to finish:

* Code style guide
* Avoiding dependencies
* Documentation for each Kongponent
* Test coverage
* Git branch name and commit message structure
* PR requirements (including a template)
* Contact info for questions and submitting tickets
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,65 @@
+# Contributing to Kongponents 🍌
+
+Thank you for your interest in contributing to Kongponents. Please follow the guidelines below to keep our respository's commit history clean and consistent.
+
+## Branching
+
+Branch from `master`. Name the new branch with a type followed by a brief title, e.g., `fix/broken-button` or `chore/bump-version`. For a list of types, follow the same conventions used in commit messages below. 
+
+Limit the scope of the branch to one particular outcome. If you encounter other improvements you can make during the course of working on the branch, e.g., if you discover another bug you could fix or a dependency version that needs to be increased, please maintain commit atomicity. 
+
+Rebase regularly to keep the code history flat and readable. To open a PR, even for a branch that is still in progress, see [submitting a PR](README.md#submitting-a-pr).
+
+## Commit Message Format
+
+To maintain a healthy Git history, please write your commit messages as follows:
+
+  * Use *present tense*
+  * Prefix your message with a [type](#type) and a [scope](#scope)
+  * The header of your message should not exceed 50 characters
+  * If a [body](#body) is necessary, include a blank line between the header and the body
+  * The body of your message should not contain lines longer than 72 characters
+
+Below is a template of what a commit message should look like:
+
+```
+<type>(<scope>) <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+### Type
+
+The type of your commit indicates what type of change this commit is about. The
+accepted types are:
+
+* *feat*: A new feature
+* *fix*: A bug fix
+* *tests*: A change that is purely related to the test suite only (fixing a test, adding a test, improving its reliability, etc...)
+* *docs*: Changes to the README.md, this file, or other such documents
+* *style*: Changes that do not affect the meaning of the code (white-space trimming, formatting, etc...)
+* *perf*: A code change that significantly improves performance
+* *refactor*: A code change that neither fixes a bug nor adds a feature, and is too big to be considered just perf
+* *chore*: Maintenance changes related to code cleaning that isn't considered part of a refactor, build process updates, dependency bumps, or auxiliary tools and libraries updates (e.g. Lerna, Storybook, Styleguide)
+
+### Scope
+
+The Kongponent or any other part of the codebase affected by your change. Examples of using type and scope:
+
+* docs(readme)
+* feat(kmodal)
+* fix(kbutton)
+
+### Body
+
+The body of your commit message should contain a detailed description of your changes if you predict they will not be immediately clear to a reviewer. 
+
+Ideally, if the change is significant, you should explain its motivation, the chosen implementation, and justify it.
+
+As previously mentioned, lines in the commit messages should not exceed 72 characters.
+
+### Footer
+
+The footer is the ideal place to link to related material about the change, e.g. related GitHub issues, Pull Requests, Jira tickets.
diff --git a/README.md b/README.md
@@ -1,6 +1,10 @@
 # Kongponents 🍌
 
-Kong Component [Vue](https://vuejs.org/) library. [kong.github.io/kongponents/](https://kong.github.io/kongponents/)
+Welcome to Kongponents, Kong's very own [Vue](https://vuejs.org/) [component](https://vuejs.org/v2/guide/components.html#ad) library. See the reference documentation for each Kongponent at [kong.github.io/kongponents/](https://kong.github.io/kongponents/)
+
+Kongponents offer multiple teams the ability to reuse frequently needed UI elements, reducing each team's efforts. They should be simple on the surface and extensible. Kongponents should also be maintainable and easy to compose with others (for example, KButton is reused in KModal and KEmptyState). Unique components that are tightly related to a particular application should not be turned into Kongponents.
+
+If you are interested in contributing to the Kongponents repo, please review [CONTRIBUTING.md](CONTRIBUTING.md) for Git standards and release guidelines.
 
 ## Installation
 
@@ -57,14 +61,75 @@ kpm --help
 
 ```
 
-### Creating Kongponents:
+## Creating a New Kongponent
+
+If you are interested in contributing to the Kongponents repo, please review [CONTRIBUTING.md](CONTRIBUTING.md) for Git standards.
 
 Run the following command to create a new component built from the [template files](cli/template)
 
 ```bash
 kpm create <kongponent_name> -d <kongponent_description>
 ```
 
+### Style Guidelines
+
+All Kongponents should abide by the essential rules in Vue's [style guide](https://vuejs.org/v2/style-guide/). To maintain consistency, use conventions that already exist in other Kongponents: name the Kongponent with K, use camel case, and be as accurate as possible in naming Kongponents.
+
+Provide as much detail in the [prop definitions](https://vuejs.org/v2/style-guide/#Prop-definitions-essential) as possible to (1) make the code self-documenting and (2) enable Vue to warn developers if they are providing props to the Kongponent incorrectly.  
+
+Use predicates in names of data properties or methods that return booleans. For example, use “isDisabled” and “hasBorder” instead of “disabled” and “border”. Avoid abbreviations unless they are commonly used acronyms, e.g., “isUrl”, “http”.
+
+### Avoiding Dependencies
+
+Avoid introducing new dependencies into Kongponents. Part of this library's value is that it reduces the need for external UI libraries such as Vue Bootstrap. More broadly, dependencies in any component library could introduce stability and security issues, and it would quickly become difficult to prevent redundant dependencies with different versions in a given application.
+
+### Documenting Kongponents
+
+In addition to detailed prop definitions, each Kongponent must include a `README` that models how the Kongponent and its related attributes would appear from the surface:
+
+```javascript
+const attributes = {
+  description: '{%kongponent_description%}',
+}
+
+<{%kongponent_name%} :description="attributes.description">
+  Hello from a slot
+</{%kongponent_name%}>
+```
+
+VSCode has built-in descriptions and type checking for [JSDOC](https://github.com/jsdoc3/jsdoc) that avoids the need for TypeScript. Generate comments within code on as many methods as possible.
+
+### Test Coverage
+
+Write unit tests for base functionality (e.g., that buttons work correctly, text displays on banners), as well as edge cases (e.g., invalid input, returning to an empty state after clearing the input).
+
+## Submitting a PR
+
+A PR needs at least one approving review before it can be merged. To open a PR for a branch that is still a work in progress, use the WIP tag to let others know that it is not intended for final review. 
+
+Before publishing a new version as detailed in [Publishing to NPM](#publishing-to-npm), update the version in `package.json`. If creating a new Kongponent, use `0.0.1-beta.1`. If updating, add `1` after `beta`.
+
+Create a Git tag for the branch with the matching version number.
+
+The WIP tag should not be removed until tests are passing and the versions in `package.json` and the release branch are up to date.
+
+## Reviewing a PR
+
+To review a PR, check that it meets the following requirements:
+
+  * Does not introduce dependencies
+  * Functional: all changes do not break existing APIs and if so, bump major version.
+  * Tests pass: check the output of  `yarn test packages/<Kongponent>`
+  * Naming: the files and the method and prop variables use the same naming conventions as other Kongponents
+  * Framework style: abides by the essential rules in [Vue's style guide](https://vuejs.org/v2/style-guide/)
+  * Cleanliness: does not have formatting issues, unused code (e.g., console.logs), or leftover comments
+  * Docs: includes a technically accurate README, uses JSDOC where appropriate
+  * Version: `package.json` and the release tag both reflect the same, accurate version
+
+If any of the above are missing, the PR should be blocked until they are resolved. Needless to say, this list is not exhaustive. If the PR introduces anything that would be detrimental to developers or users, it should be blocked. 
+
+There are often times when a suggested change would simply be a “nice-to-have”, and when blocking would create friction. The reviewer should note that the comment is a preference, and the PR author has discretion over how to address the request. In such cases, a reviewer's “approval” is pending the author's response to the feedback, rather than a change to the code.
+
 ## Publishing to NPM
 
 We use [Lerna](https://lernajs.io/) to publish Kongponents. 
@@ -92,6 +157,8 @@ Follow the prompt as noted before.
 
 Kongponents is a mono repo, managed by Lerna. It follows suggested Lerna directory structure with a root `packages` folder which contain all the components. Lerna allows easier developer experience through a single git repository, managed dependencies, and easy publishing of individual components. It's like blowing up the monolith, but you still have the perks of the monolith during development.
 
+To see the structure of the Kongponent template created through the CLI, see: https://github.com/Kong/kongponents/tree/master/cli/template
+
 ```
 packages                     # root directory of all components
 ├── KButton                  
@@ -115,3 +182,11 @@ packages                     # root directory of all components
 .   .
 .
 ```
+
+## Asking Questions and Submitting Tickets
+
+If you encounter difficulty working with Kongponents, either in your own codebase or in contributing to this one, post questions in `#design-pattern-lib` or `#team-interfaces`. If you discover a problem but are unsure whether it's a bug, it may be resolved faster in the channels.
+
+Log bugs with [Team Interfaces](https://konghq.atlassian.net/secure/RapidBoard.jspa?projectKey=INTF). Document the steps to replicate the bug with screenshots and error messages, if possible. Please also mention the browser, the versions and branches of the applications involved (e.g., [`kong-admin`](https://github.com/Kong/kong-admin), [`kong-ee`](https://github.com/Kong/kong-ee)), and your configuration for Kong.
+
+To request a feature or an improvement, describe use cases for the team to review in `#design-pattern-lib` or `#team-interfaces`. If an alternative already exists, mention why a Kongponent would be a better approach. 
diff --git a/pull_request_template.md b/pull_request_template.md
@@ -0,0 +1,14 @@
+### Summary
+
+#### Changes made:
+*
+
+### PR Checklist
+- [ ] Does not introduce dependencies
+- [ ] **Functional:** all changes do not break existing APIs and if so, bump major version.
+- [ ] **Tests pass:** check the output of yarn test packages/<Kongponent>
+- [ ] **Naming:** the files and the method and prop variables use the same naming conventions as other Kongponents
+- [ ] **Framework style:** abides by the essential rules in Vue's style guide
+- [ ] **Cleanliness:** does not have formatting issues, unused code (e.g., console.logs), or leftover comments
+- [ ] **Docs:** includes a technically accurate README, uses JSDOC where appropriate
+- [ ] **Version:** package.json and the release tag both reflect the same, accurate version
