xref: /openbmc/webui-vue/CONTRIBUTING.md (revision 6b6926e2e1585856a2665eeac7955a47bae4a8df)
1# Contributing to WebUI-Vue
2
3:+1::tada: First off, thanks for taking the time to contribute! :+1::tada:
4
5The following is a set of guidelines for contributing to the OpenBMC Web UI.
6
7## Table of contents
8
9- [Project Setup](#project-setup)
10- [Asking Questions](#asking-questions)
11- [Submitting Bugs](#submitting-bugs)
12- [User Research](#user-research)
13- [Design Reviews](#design-reviews)
14- [Help Wanted](#help-wanted)
15- [Code Reviews](#code-reviews)
16
17## Project Setup
18
19### Set up Gerrit account
20
21The OpenBMC projects use Gerrit for code review. Use the
22[OpenBMC Gerrit Setup/Integration guidelines](https://github.com/openbmc/docs/blob/master/development/gerrit-setup.md)
23to set up your Gerrit account.
24
25### Clone repo from Gerrit
26
27Since we use Gerrit to manage all the code contributions, it is not necessary to
28create a fork from GitHub. Read more about submitting a code review in the
29[Code Reviews section](#code-reviews) below.
30
311. Visit <https://gerrit.openbmc-project.xyz/admin/repos/openbmc/webui-vue>
322. Clone the repo using the `Clone with commit-msg hook` link
33   - Windows users may need to separate the two commands depending on if they
34     have installed a Bash emulator like `Git for Windows` or `CMDER` or
35     installed the `Windows Subsystem for Linux`.
36
37### Install Dependencies
38
39```shell
40npm install
41```
42
43### Create a .env file
44
451. Create the following file in the root directory
46   - .env.development.local
471. Add the following environment variable
48   - `BASE_URL="https://<BMC IP address or FQDN>"`
49
50### Compile and hot-reload for development
51
52```shell
53npm run serve
54```
55
56### Run Documentation Locally (Vuepress static site generation)
57
58```shell
59npm run docs:serve
60```
61
62### Run unit tests
63
64```shell
65npm run test:unit
66```
67
68### Lint and fix files
69
70```shell
71npm run lint
72```
73
74This project and everyone participating are required to follow the
75[OpenBMC Code of Conduct](https://github.com/openbmc/docs/blob/master/code-of-conduct.md).
76
77## Asking Questions
78
79The OpenBMC communicates using a mail list and the Discord channel. Although you
80could create a GitHub issue to ask a question, a better option would be to ask
81your question using the email list or Discord channel.
82
83- Mail: <openbmc@lists.ozlabs.org> <https://lists.ozlabs.org/listinfo/openbmc>
84- Discord: <https://discord.gg/69Km47zH98>
85
86### Submitting Bugs
87
88Before submitting an issue, please search through the
89[existing GitHub issues](https://github.com/openbmc/webui-vue/issues) to see if
90someone already reported the problem. If the issue does not exist, use the
91[Bug report template](https://github.com/openbmc/webui-vue/issues/new?assignees=&labels=&template=bug_report.md&title=)
92to report the problem.
93
94Before submitting a request for a new feature, please search through the
95[existing GitHub issues](https://github.com/openbmc/webui-vue/issues). If no one
96has suggested the idea previously, use the
97[Feature request template](https://github.com/openbmc/webui-vue/issues/new?assignees=&labels=&template=feature_request.md&title=)
98to submit a new feature request.
99
100## User Research
101
102To improve the OpenBMC Web UI, we are actively seeking end-user feedback through
103the IBM Design Partner program.
104
105### What is an OpenBMC Design Partner?
106
107Contribute your feedback and bring your domain expertise to help us improve the
108OpenBMC GUI. The time commitment is minimal: 1-hour feedback sessions conducted
109remotely via Webex, 1 to 2 times per month. Activities may include exploratory
110interviews, participatory design, periodic surveys, or usability testing
111sessions.
112
113Note: IBM requires all user research participants to sign a Feedback Program
114Agreement (FPA), describing how IBM complies with the latest GDPR guidelines.
115The FPA only needs to be signed once to cover your company or entity's
116participation.
117
118## Design Reviews
119
120When making changes to an existing design, we create a design review issue in
121GitHub. We then send an email to the community and review the changes in the
122[OpenBMC GUI Design Workgroup](https://github.com/openbmc/openbmc/wiki/GUI-Design-work-group).
123
124## Help Wanted
125
126New features and bugs ready for development will be tagged with the
127`Help Wanted` tag and added to the
128[Help Wanted Project](https://github.com/openbmc/webui-vue/projects/2). If you
129want to pick up a story, add a comment stating your interest, and a maintainer
130will assign the story and move it to the `In Progress` column in the Project
131Kanban board.
132
133## Code Reviews
134
135The OpenBMC project uses Gerrit for all code reviews. Please do not create a
136GitHub pull request.
137
1381. Commit your changes, adding a Signed-off-by line to it:
139   `git commit --signoff`
1401. Write a [good commit message](https://chris.beams.io/posts/git-commit/)
141   - Separate subject from the body with a blank line
142   - Limit the subject line to 50 characters
143   - Capitalize the subject line
144   - Do not end the subject line with a period
145   - Use the imperative mood in the subject line
146   - Wrap the body at 72 characters
147   - Use the body to explain what and why vs. how
148
1491. Push your changes to Gerrit for code review:
150   `git push origin HEAD:refs/for/master`
1511. Assign reviewers
152