Skip to content

Commit

Permalink
docs: Create contribution guidelines and update docs (#426)
Browse files Browse the repository at this point in the history
* docs: Start documenting contributing guidelines.

* docs: Create Pull Request template

Co-authored-by: connor-baer <[email protected]>

* docs: Add design system flow chart to contributing docs.

* docs: Update "Getting Start" developer docs.

* docs: Add useful commands for running the project and tests.

* docs: Adjust docs about global styles in Circuit.

* docs: Adjust dependencies needed to add emotion to a circuit project.

* docs: Remove the how to document page.

* docs: Remove empty FAQ page.

* docs: Re-enable custom index and update favicon.

* docs: Add global styles to docz wrapper.

* docs: Work on proposal for component design principles.

* docs: Update documentation on emotion theming and fonts.

* docs: Fix fonts docs referencing outdated function.

* docs: Remove extraneous line from getting started developers page.

* docs: Adapt docz to use circuit colors.

* docs: Add header to docs helpers, remove unused components.

* docs: Reformat dev principles in docs.

* docs: Move location of Principles page in docz.

* docs: Update message about using the distributed version of Circuit.

* docs: Adjust text on developers getting started page.

* docs: Add docs for Badge.

* docs: Add docs for Message.

* docs: Add docs for progress bar.

* docs: Add docs for tag component.

* docs: Remove DocButton file.

* docs: Add empty doc for autocomplete input.

* docs: Add search input to form page.

* docs: Add toggle.

* docs: Add calendar component.

* docs: Fix modal broken in docs.

* docs: Remove non-rendered props in docs pages.

* docs: Add pagination component.

* docs: Add sidebar docs.

* docs: Add more sidebar docs.

* docs(docs): update best practices section for principles

* docs: Put changelog directly in docs menu.

* Remove component status page in favor of on-page statuses.

* Add issue template to suggest tech improvement

* Fix Tech improvement issue template

* Fix emotion-theming link

Emotion moved to a monorepo structure and this broke the link

* Fix error in GlobalStyles code snippet example

The wrong variable name was passed as custom prop

* Fix typo on Fonts page

* Indent code snippets to fix ordered list numbering

* Update usage of theme.standard to theme.circuit in the docs.

* Remove extra spaces in List code snippets

* Fix ProgressBar percentage or fraction code snippet

- Label says 33%, the props should be max={3} value={1}
- Harmonize sizes, the snippet with example sizes comes after

* Handle missing docz hashrouter with 404 redirect for gh-pages

* Mention create-sumup-react-app and circuit-deck tools in Getting Started

* Fix use of Emotion styled API in example snippet

* Add AutoCompleteInpu to Forms page

* Document AutoCompleteTags on Forms page

* Fix bold styling for Do not list item

* Adding blockquote documentation

* Add docs for the SidebarContext component

* Fix Table custom sorting code snippet

* Document ButtonGroup on the Button page

* Rewrite Autocomplete Tags doc line

* Document ListView on Card page

* Remove margins in InlineNotification example snipets

* Add section on notification messages to Message

* Write Inline Notification intro

Point to Message for notifications removed from the content flow

* Mention InlineNotification for in-flow notifications in NotificationList

* Scaffold out Tabs documentation

* Write docs for CardScheme

* Write draft Loading Button docs

Use a state hook in button.js to render a dynamic component in the Playground

* Adding button documentation

* Adding calendar docs

* Adding card docs

* Adding HR docs

* Adding image docs

* Add statuses to components.

* Add changes to statuses.

* Adding inline notification docs

* docs: add pagination and update message

* Add deprecation process to contributing file.

* docs: add selector and update sidebar

* docs: add state to Sidebar playground

* docs: add table and toggle

* docs: refactor LoadingButton helper component to render a better Playground example

- Improve the markup shown in the Docz Playground, showing three buttons instead of a single
element
- Add a Playground comment explaining an implementation of LoadingButton could be found in
the Storybook
- Refactor the button.js helper component to deal with a simple exitAnimation prop
from the Playground example

* docs: update tech improvement issue template name

* docs: fix console.log to console.warn in CONTRIBUTING

* docs: add Props tables and lint

* docs: add stateful helper component for Selector Playground

* docs(docs): describe the release process

* fix(docs): fix anchor link

* docs: add design principles, typography and card schemes

* docs: update blockquote and add getting started for designers
  • Loading branch information
mlent authored and joaovtg committed Jul 15, 2019
1 parent 966fe5d commit 71a059f
Show file tree
Hide file tree
Showing 53 changed files with 1,982 additions and 559 deletions.
199 changes: 199 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
# How to contribute

So you want to contribute to Circuit UI? That's awesome. Here are a few
things that can help you make it a reality.

## Code of conduct

We expect all participants to read and adhere to our [code of conduct](/CODE_OF_CONDUCT.md).

## Semantic versioning

Circuit UI follows semantic versioning. In short, this means we use patch versions
for bugfixes, minor versions for new features, and major versions for
breaking changes. Our [release process](#Releases) is automated using [semantic-release](https://github.com/semantic-release/semantic-release)
which adheres to the [conventional commit message format](https://www.conventionalcommits.org).

As a result, our changelog is pretty tidy. You can [read our changelog on GitHub](https://github.com/sumup/circuit-ui/releases).

## Bugs

We use the [GitHub issues](https://github.com/sumup/circuit-ui/issues) to track
all our bugs and feature requests.

When [submitting a new issue](https://github.com/sumup/circuit-ui/issues/new),
please check that it hasn't already been raised by someone else. We've provided
a template for new issues which will help you structure your issue to ensure it
can be picked up and actioned easily.

Please provide as much information possible detailing what you're currently
experiencing and what you'd expect to experience.

## Proposing a change

![Component pattern addition](/component-addition-flowchart.png)

### Creating or changing a component

Our process for introducing changes to Circuit UI largely follow the Vanilla
design system process published by Canonical.

#### Creating new components

- You should favor using existing components rather than creating new ones.
- You should favor adapting existing components rather than creating new ones.
- You must contribute new components through the design system (rather than
coding them directly in the application) if the component is likely to be
used in more than one project.
- You should create an issue in the Circuit UI GitHub repo with the proposed
components using the appropriate issue type, _before_ implementing the
component.
- You should _not_ contribute components that are highly specific to the
use-case of a single application. If possibly, generalize it!

#### Adapting an existing component

- You may open a pull request with your proposed changes without opening an
issue in Circuit UI, so long as those changes could be classified as
minor.

#### Workflow

- Either a designer or a developer must open the issue in Circuit UI to propose
a new component or changes to an existing component.
- New components must be reviewed by two designers and two developers from
different teams.
- We should strive to decide whether we adopt a new component, if it's needed
for a feature, within one week of opening the issue.
- We should strive to decide whether we accept changes to an existing
component within one week of opening the issue.

### Technical changes or improvements

- You should open an issue in Circuit UI with your proposed change using the
"Suggest tech improvement" issue type.

## Your first pull request

## Development workflow

We develop our components in Storybook. To start running Storybook on your
local machine, run:

```
yarn storybook
```

To run unit tests in watch mode, run:

```
yarn test:unit:watch
```

As for linting and formatting, you can configure your editor to automatically
lint and format your code on save. For this purpose, we're using Prettier
and ESLint.

If you need to do it manually, you can run:

```
yarn unit:lint-js
yarn fix
```

### Local testing

While making changes to Circuit UI, you might want to test them in your
application. You can do so by [linking the two projects](https://yarnpkg.com/lang/en/docs/cli/link/)
locally.

Inside the Circuit UI project folder, run:

```
yarn link
```

Then, in your application project folder, run:

```
yarn link @sumup/circuit-ui
```

### Deprecation process

The purpose of deprecating a component or a feature is to warn people that
it should not be used anymore, and that support will be removed in the future.
You can either offer a preferred solution, or it may be that the feature is
no longer needed.

1. **Communicate intent to deprecate.** Please open an issue in the repo with
issue type "Deprecation", and share this issue with [email protected] and
[email protected]. Go through the product repos and find instances of
the component in use, and proactively communicate with the teams responsible
for those features. Give your reasoning about _why_ you believe the feature
should be deprecated, and discuss the impact on the teams that rely on
that feature today.
2. **Decide on a timeline.** Based on the feedback you receive, come up with
a timeline, including the people who are affected by the change. Generally
speaking, 3-6 months is ample time. Document the planned date of removal
in the original deprecation issue.
3. **Add a notice to the docs and to the code.** Introduce the deprecation
warning in a minor release. Change the status badge on the component page
to "Deprecated" and add a `console.warn(`ComponentName is deprecated and will be removed in version X.0.0`)`
to the `render()` function of the component, or generally on the first
run of an instance of a component or feature.
4. **Wait for the deadline.** You may still need to fix critical bugs during the
deprecation period, but we should try and offer alternatives where possible.
5. **Communicate it one more time!** Give one last warning to people involved
that the deadline is imminent.
6. **Delete it.** Create a PR deleting the deprecated functionality, which should
signal a major version bump.

In some cases, you can also introduce a completely new version of the component
alongside the old, especially in cases where teams need longer to migrate
to the new component. For example, changing the SideNav component.

## Releases

We have a couple of special branches that are automatically released whenever
you merge code into them.

- `beta` — This is a branch you can use to test your changes integrated with
other branches before it is ready to be PR'd to `canary`. It is also useful
if you need to deploy the changes somewhere to test them. `beta` is a
throw-away branch that can be recreated from `canary` at any time.
- `canary` - The step before `master`. This is where we prepare a group of
changes for the next release. Code on `canary` should be tested and stable.
Usually, `canary` is a couple of commits ahead of `master`.
- `master` - A merge to `master` will release a new version of the library.
Code on `master` is stable and production-tested.
- `next` - This branch is used to develop the next major version in parallel.
It is the only branch that can contain breaking changes.

When you merge into one of these release branches, `semantic-release` runs in
CI and automatically:

- pushes a new version to the respective release channel on NPM (`beta`,
`canary`, `latest` or `next`)
- updates the release notes on GitHub based on the commit messages since the
previous release
- and posts comments on any PRs and issues that are included in the release.

To install the most recent version from a release channel, run:

```
yarn add @sumup/circuit-ui@<release-channel>
```


### Troubleshooting

- **The release failed.** This can happen if you merge multiple times to a
release branch in short succession. The first CI job will fail because the
branch on GitHub is ahead of the branch that was checked out in CI.
`semantic-release` will open an issue to alert you of the failure. You can
simply wait for the last CI job to finish. It should succeed and will
automatically close the issue.
- **My commit doesn't show in the release notes.** Make sure that your commit
message follows the [conventional commit format](https://www.conventionalcommits.org).
Otherwise, `semantic-release` can't understand your commit and will omit it.
18 changes: 18 additions & 0 deletions .github/ISSUE_TEMPLATE/suggest-tech-improvement.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
name: Suggest tech improvement
about: Suggest an improvement to the technology and tools behind Circuit UI
---

## Suggested technology

- What technology do you suggest we start using?
- What technology (if any) would it replace?
- What problem does it solve?

## Alternatives

What are the alternatives you've explored? Why choose one over the other?

## Potential downsides

Do you see any downsides to this technology?
17 changes: 17 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
Addresses #ticket-number.

## Purpose

_Describe what you are trying to accomplish_

## Approach and changes

_Describe how you solved the problem_

## Definition of done

* [ ] Development completed
* [ ] Reviewers assigned
* [ ] Unit and integration tests
* [ ] Meets minimum browser support
* [ ] Meets accessibility requirements
Binary file added .github/component-addition-flowchart.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 9 additions & 0 deletions docs/404.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<!DOCTYPE html>
<html lang="en">
<head>
<script>
location.pathname = '/'
</script>
</head>
<body></body>
</html>
8 changes: 0 additions & 8 deletions docs/content/changelog.mdx

This file was deleted.

22 changes: 0 additions & 22 deletions docs/content/component-status/components/Statuses.js

This file was deleted.

85 changes: 0 additions & 85 deletions docs/content/component-status/index.mdx

This file was deleted.

12 changes: 0 additions & 12 deletions docs/content/components/DocButton.js

This file was deleted.

Loading

0 comments on commit 71a059f

Please sign in to comment.