|
| 1 | +# Contributing to AWC |
| 2 | + |
| 3 | +## Getting started |
| 4 | + |
| 5 | +### Machine setup |
| 6 | + |
| 7 | +To work with the AWC [monorepo](https://en.wikipedia.org/wiki/Monorepo) you'll need Git, Node.js, and npm setup on your machine. |
| 8 | + |
| 9 | +AWC uses Git as its source control system. If you haven't already installed it, you can download it [here](https://git-scm.com/downloads) or if you prefer a GUI-based approach, try [GitHub Desktop](https://desktop.github.com/). |
| 10 | + |
| 11 | +Once Git is installed, you'll also need Node.js, which AWC uses as its JavaScript runtime, enabling its build and test scripts. Node.js instructions and downloads for your preferred OS can be found [here](https://nodejs.org/en/). |
| 12 | + |
| 13 | +### Cloning the repository |
| 14 | + |
| 15 | +Now that your machine is setup, you can clone the AWC repository. Open a terminal and run this command: |
| 16 | + |
| 17 | +```shell |
| 18 | +git clone https://github.com/adaptive-web/adaptive-web-components.git |
| 19 | +``` |
| 20 | +Cloning via SSH: |
| 21 | + |
| 22 | +```shell |
| 23 | +git clone [email protected]:adaptive-web/adaptive-web-components.git |
| 24 | +``` |
| 25 | + |
| 26 | +### Installing and building |
| 27 | + |
| 28 | +From within the `adaptive-web-components` folder where you've cloned the repo, install all package dependencies and build all workspaces (local dependencies) with this command: |
| 29 | + |
| 30 | +```bash |
| 31 | +npm install & npm run build |
| 32 | +``` |
| 33 | + |
| 34 | +After the initial install, you can re-build all workspaces in the future with: |
| 35 | + |
| 36 | +```bash |
| 37 | +npm run build |
| 38 | +``` |
| 39 | + |
| 40 | +### Developing in `adaptive-web-components` |
| 41 | +If you're interested in contributing changes to the `adaptive-web-components` component library, start by navigating to the `packages/adaptive-web-components` directory and starting the Storybook local server there. |
| 42 | + |
| 43 | +```bash |
| 44 | +cd packages/adaptive-web-components |
| 45 | +npm run start |
| 46 | +``` |
| 47 | +Storybook will automatically open in a browser window at `localhost:6006`. |
| 48 | + |
| 49 | +### Submitting a pull request |
| 50 | + |
| 51 | +If you'd like to contribute by fixing a bug, implementing a feature, or even correcting typos in our documentation, you'll want to submit a pull request. Before submitting a pull request, be sure to [rebase](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) your branch (typically from master) or use the *merge* button provided by GitHub. |
| 52 | + |
| 53 | +### Merging a pull request |
| 54 | + |
| 55 | +If you are merging a pull request, be sure to use the pull request title as the commit title. The title should follow the [conventional commit guidelines](https://www.conventionalcommits.org/). It is recommended that if you are merging in pull requests regularly that you add a browser extension that will auto-correct the title for you. A few that should do this are [Refined GitHub](https://github.com/sindresorhus/refined-github) and [Squashed Merge Message](https://github.com/zachwhaley/squashed-merge-message). |
| 56 | + |
| 57 | +### Recommended Settings for Visual Studio Code |
| 58 | + |
| 59 | +You can use any code editor you like when working with the AWC monorepo. One of our favorites is [Visual Studio Code](https://code.visualstudio.com/). VS Code has great autocomplete support for TypeScript and JavaScript APIs, as well as a rich ecosystem of plugins. |
| 60 | + |
| 61 | +Default VS Code settings for this project are configured as [Workspace settings](https://code.visualstudio.com/docs/getstarted/settings) in the `.vscode` directory. These settings override user settings for the workspace and are configured to ensure consistent code formatting across different environments. |
| 62 | + |
| 63 | +## Contribution policy |
| 64 | + |
| 65 | +A “Contribution” is work voluntarily submitted to a project. This submitted work can include code, documentation, design, answering questions, or submitting and triaging issues. |
| 66 | + |
| 67 | +## Guiding principle |
| 68 | + |
| 69 | +Owners, the steering committee, collaborators, code owners, and contributors work in concert with one another on behalf of the AWC community and prioritize the community's interests over their own. |
| 70 | + |
| 71 | +The development, release, and work management processes must reflect this principle. Accepting contributions to the project requires a review by collaborators. |
| 72 | + |
| 73 | +## Governance |
| 74 | + |
| 75 | +### Owners |
| 76 | + |
| 77 | +*Owners* have admin access and are responsible for the management, maintenance, and operations of the FAST repository. |
| 78 | + |
| 79 | +### Steering committee |
| 80 | + |
| 81 | +*Steering committee* members are key *collaborators* who have demonstrated design or technical expertise critical to driving the FAST project and community forward. |
| 82 | + |
| 83 | +* Aaron Wentzel |
| 84 | +* Brian Heston |
| 85 | +* Jason Falk |
| 86 | +* Rob Eisenberg |
| 87 | +* Nathan Brown |
| 88 | + |
| 89 | +### Collaborators |
| 90 | + |
| 91 | +*Collaborators* have write access and have an active and sustained impact on the project and participate in triaging issues, reviewing code, mentoring, and working to improve the architectural quality. |
| 92 | + |
| 93 | +### Code owners |
| 94 | + |
| 95 | +As subject matter experts, *code owners* approve pull requests on the packages they own. There is a required minimum of one code owner for each package. *Code owners* are listed in [CODEOWNERS](https://github.com/adaptive-web/adaptive-web-components/blob/master/.github/CODEOWNERS). |
| 96 | + |
| 97 | +### Contributors |
| 98 | + |
| 99 | +*Contributors* have read access and can be anyone who has contributed a completed pull request to the project. |
| 100 | + |
| 101 | +### Nominations & appointments |
| 102 | + |
| 103 | +* To become a *contributor*, a community member must have a pull request approved and merged into the FAST project master branch. |
| 104 | +* To become a *collaborator*, a *contributor* will petition the *steering committee*, who will approve or deny the request. |
| 105 | +* To become a *code owner*, a *collaborator* will be (a) nominated by a *steering committee* member or (b) petition the *steering committee*, who will approve or deny the request. |
| 106 | +* To join the *steering committee*, a *collaborator* will be nominated by a *steering committee* member and the *steering committee*, who will approve or deny the request. |
| 107 | + |
| 108 | +## Acceptance and consensus seeking process |
| 109 | + |
| 110 | +Acceptance of contributions follows the consensus-seeking process. |
| 111 | + |
| 112 | +All pull requests must be approved by an assigned *collaborator* before the pull request can be accepted. A *collaborator* will be assigned to a pull request within [a reasonable period of time](#response-time) of the pull request creation. The assignee will be responsible for: |
| 113 | + |
| 114 | +1. Reviewing the pull request if they are not the creator of it |
| 115 | +2. Adding any additional reviewers to review at their discretion |
| 116 | +3. Ensuring the pull request is given feedback in [a reasonable period of time](#response-time) from *collaborators* or *code owners* with the expertise to evaluate the changes |
| 117 | +4. Merging the pull request |
| 118 | + |
| 119 | +When a pull request : (a) has a significant impact on the project, (b) is inherently controversial, or (c) has not reached consensus with *collaborators*; add a "status:controversial" label to the pull request for the *steering committee* to review the pull request. Pull requests labeled with "status:controversial" are not approved until the *steering committee* reviews the issue and makes a decision. |
| 120 | + |
| 121 | +Additionally, *owners* can temporarily enable [interaction limits](https://help.github.com/articles/limiting-interactions-with-your-repository/) to allow a "cool-down" period when hot topics become disruptive. |
| 122 | + |
| 123 | +Specific *collaborators* or *code owners* can be added to a pull request by including their user alias in the "Reviewers" section. |
| 124 | + |
| 125 | +### Response time |
| 126 | + |
| 127 | +The amount of time can vary but at least 3 days during the typical working week and 5 days over weekends should be given to account for international time differences and work schedules. This is considered a reasonable period of time. |
| 128 | + |
| 129 | +## Developer's Certificate of Origin 1.1 |
| 130 | + |
| 131 | +By making a contribution to this project, I certify that: |
| 132 | + |
| 133 | +* a. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or |
| 134 | +* b. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or |
| 135 | +* c. The contribution was provided directly to me by some other person who certified (a), (b), or (c) and I have not modified it. |
| 136 | +* d. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. |
| 137 | + |
| 138 | +## Resources |
| 139 | + |
| 140 | +Several open source projects have influenced our contribution policy: |
| 141 | + |
| 142 | +* [Project Governance @Node](https://nodejs.org/en/about/governance/) |
| 143 | +* [Contributions @Node](https://github.com/nodejs/node/blob/master/CONTRIBUTING.md) |
| 144 | +* [Open Source @GitHub](https://github.com/blog/2039-adopting-the-open-code-of-conduct) |
| 145 | +* [Open Source examples @todogroup](https://github.com/todogroup/policies) |
0 commit comments