Skip to content

Commit

Permalink
chore: update the pull request template and documentation (#1230)
Browse files Browse the repository at this point in the history 
* chore: update the pull request template and documentation

* chore: update the pull request template and documentation

* Updates based on pr comments

* move file to appropriate directory
  • Loading branch information
@Falkicon
Falkicon authored Dec 27, 2018
1 parent 5263332 commit e7d8a20
Show file tree
Hide file tree
Showing 2 changed files with 37 additions and 23 deletions.
26 changes: 22 additions & 4 deletions .github/pull_request_template.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,24 @@
<body>
<!--- Provide a summary of your changes in the title field above. -->

<footer>

## Description
<!--- Describe your changes. -->

## Motivation & context
<!--- What problem does this change solve? -->
<!--- Provide a link if you are addressing an open issue. -->

## Issue type checklist
<!--- What type of change are you submitting? Check the boxes that apply: -->
- [ ] **Bug fix**: non-breaking change which fixes an issue, link to the issue above.
- [ ] **New feature**: non-breaking change that adds functionality.
- [ ] **Breaking change**: fix or feature that will cause current functionality to change.

For [details on formatting](https://github.com/Microsoft/fast-dna/wiki/pull-request-guidance) pull requests.
## Process & policy checklist
<!--- Review the list and check the boxes that apply. -->
- [ ] I have added tests for my changes.
- [ ] I have tested my changes.
- [ ] I have updated the project documentation to reflect my changes.
- [ ] I have read the CONTRIBUTING documentation and followed the standards set for this project.


Click here for details on [formatting pull requests](https://microsoft.github.io/fast-dna/docs/contributing/working#formatting-messages).
34 changes: 15 additions & 19 deletions docs/en/contributing/working.md
View file
Original file line number Diff line number Diff line change
@@ -1,26 +1,24 @@
---
id: working
title: Contributing
title: Working
sidebar_label: Working
---

# Working

## Managing Issues

Well crafted issues improve the speed that work can be triaged, understood, and completed. To help guide this process [issue templates](https://github.com/Microsoft/fast-dna/tree/master/.github/ISSUE_TEMPLATE) exist to allow users to choose an appropriate [bug report](https://github.com/Microsoft/fast-dna/blob/master/.github/ISSUE_TEMPLATE/Bug_report.md), [feature request](https://github.com/Microsoft/fast-dna/blob/master/.github/ISSUE_TEMPLATE/Feature_request.md), or [custom template](https://github.com/Microsoft/fast-dna/blob/master/.github/ISSUE_TEMPLATE/Custom.md).
Well crafted issues improve the speed that work can be triaged, understood, and completed. To help guide this process [issue templates](https://github.com/Microsoft/fast-dna/tree/master/.github/ISSUE_TEMPLATE) exist to allow users to choose an appropriate [bug report](https://github.com/Microsoft/fast-dna/blob/master/.github/ISSUE_TEMPLATE/report-a-bug.md) or [feature request](https://github.com/Microsoft/fast-dna/blob/master/.github/ISSUE_TEMPLATE/request-a-feature.md).

Here's a good resource for [Do's and Don'ts](https://hackernoon.com/45-github-issues-dos-and-donts-dfec9ab4b612) when working with bugs, issues, and requests.
Here's an excellent resource for [do's and don'ts](https://hackernoon.com/45-github-issues-dos-and-donts-dfec9ab4b612) when working with bugs, issues, and requests.

[GitHub Labels](https://developer.github.com/v3/issues/labels/) are used to manage issues broadly considered work items grouped by color and prefixed by label name.
[GitHub labels](https://developer.github.com/v3/issues/labels/) are used to manage issues broadly considered work items grouped by color and prefixed by label name.

## Pull requests

When landing a pull request (PR), individuals must modify the original commit message to include comprehensive details. This detail along with other git history meta information deploys as part of the documentation changelog history. Changlogs are generated by [Lerna](https://lernajs.io/) using [Conventional commits](https://conventionalcommits.org/).
When landing a pull request (PR), individuals must modify the original commit message to include comprehensive details. This detail along with other git history meta information deploys as part of the documentation changelog history. Changelogs are generated by [Lerna](https://lernajs.io/) using [conventional commits](https://conventionalcommits.org/).

PR comments should include the issue number per the [github closing issue keywords](https://help.github.com/articles/closing-issues-using-keywords/) documentation.

One or more collaborators will automatically be assigned to review each PR based on areas of [ownership](https://github.com/Microsoft/fast-dna/blob/master/.github/CODEOWNERS).
One or more collaborators are automatically assigned to review each PR based on areas of [ownership](https://github.com/Microsoft/fast-dna/blob/master/.github/CODEOWNERS).

**`<type>`** is required to be at least one of the following:

Expand Down Expand Up @@ -50,17 +48,15 @@ chore: add unit-tests for all components
fix: update MSFT design system to use 3px border radius
```

### Formatting messages

Optionally, include more detail in the message.
### Pull request template

`<body>` is used to provide clarity and context to the description.
In addition to providing a properly formatted title for your pull request, we offer a template that will help guide you toward appropriate best practices and processes as well as provide additional information which will give those reviewing your request the context they need.

`<footer>` is used to provide additional metadata about the pull request such as issue fixing (fix #19, close #19, resolve #19). Additionally, is used to denote [breaking changes](https://www.conventionalcommits.org/en/v1.0.0-beta.2/#specification).
Open the [pull request template](https://github.com/Microsoft/fast-dna/blob/master/.github/pull_request_template.md).

### Interim commits

The above outlines the format for the **final** commit, but contributors will have many interim commits while working on their branch. These commits should be succinct, concise, and consistent for best readability. Always remember, a diff will tell you _what_ changed in a commit, but only the commit message can properly tell you _why_.
The above outlines the format for the **final** commit, but contributors have many interim commits while working on their branch. These commits should be succinct, concise, and consistent for best readability. Always remember, a diff tells you _what_ changed in a commit, but only the commit message can adequately tell you _why_.

Typical interim commits may look like the following:

Expand All @@ -72,19 +68,19 @@ e142fd1 Rebase with master
ac8326d Fix ts-lint errors
```

As a core philosophy we prefer [rebasing over merging](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
As a core philosophy, we prefer [rebasing over merging](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).

## Common commands

All "packages" share common script names for consistency along with their own documentation guides.
All "packages" share common script names for consistency along with their documentation guides.

To clean all packages.

```bash
lerna clean
```

When package files change the symbolic links will require updating.
Install remote dependencies, build, and symlink local dependencies.

```bash
lerna bootstrap
Expand All @@ -103,8 +99,8 @@ cd packages/package-name
npm run test
```

Most packages have a *watch* command that will rebuild the package's distribution when a file changes. This process can be useful when doing development across multiple packages.
Most packages have a *watch* command that rebuilds the package's distribution when a file changes. This process can be useful when doing development across multiple packages.

```bash
npm run watch
```
```

0 comments on commit e7d8a20

Please sign in to comment.