Skip to content

Commit db18f39

Browse files
alfirmanpahlepialfirmanpahlepi
committed
feat: add contributing md
1 parent 515d981 commit db18f39

File tree

1 file changed

+248
-0
lines changed

1 file changed

+248
-0
lines changed

‎CONTRIBUTING.md

+248
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# Contributing to SecondHand-FE
2+
3+
- [How to contribute](#how-to-contribute)
4+
- [Finding or creating issues](#finding-or-creating-issues)
5+
- [Open Issues](#open-issues)
6+
- [Closed Issues](#closed-issues)
7+
- [For Beginners: `good first issue` label](#for-beginners-good-first-issue-label)
8+
- [Working on issues](#working-on-issues)
9+
- [Getting ready](#getting-ready)
10+
- [Issue assignment & Communication](#issue-assignment--communication)
11+
- [Creating a Draft Pull Request](#creating-a-draft-pull-request)
12+
- [Formatting Pull Request Description](#formatting-pull-request-description)
13+
- [Disabling GitHub Actions](#disabling-github-actions)
14+
- [FAQ](#faq)
15+
- [Why are we using English in our issues & PRs?](#why-are-we-using-english-in-our-issues--prs)
16+
- [Additional Notes](#additional-notes)
17+
- [Commitlint](#commitlint)
18+
- [References](#references)
19+
- [Conventional Commits](#conventional-commits)
20+
- [Commit types](#commit-types)
21+
- [Commit scopes](#commit-scopes)
22+
- [Issue and Pull Request Labels](#issue-and-pull-request-labels)
23+
- [Type of Issue and Issue State](#type-of-issue-and-issue-state)
24+
- [Topic Categories](#topic-categories)
25+
26+
## How to contribute
27+
28+
In this project, we are heavily utilising GitHub features to document and signal any progress in the website development.
29+
30+
### Finding or creating issues
31+
32+
Most contributions start from defining issues. Anyone can open an issue for discussion. You can head to [this link](https://guides.github.com/features/issues/) for deep understanding about Issues. Specifically, you can start finding several Issues in [our Issues tab](https://github.com/WhiteClover4/SecondHand-FE/issues). There are only two categories in Issues section, Open and Closed.
33+
34+
#### Open Issues
35+
36+
Open Issues are issues that need more attention and need to be resolved. Contributors should pick any of the Open Issues and start working on them.
37+
38+
#### Closed Issues
39+
40+
Closed Issues are issues that have been completed or doesn't need further action. Closed issues can be reopened if contributors find any issues related to it sometime in the future.
41+
42+
Please pay attention on every issue attribute. Every issue might be referenced by other contributors through [Linked Pull Requests](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). If an issue has a linked pull request, that means the issue is currently being handled. To avoid working on the same issue, contributors were strongly encouraged to submit a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) first when they start working on an issue.
43+
44+
#### For Beginners: `good first issue` label
45+
46+
As mentioned [here](https://github.blog/2020-01-22-browse-good-first-issues-to-start-contributing-to-open-source/), `good first issue` is a label feature from GitHub which created to help beginner contributors in contributing to an open-source project. `good first issue` informed us about the difficulty level of an issue. This means that an issue with `good first issue` label suits perfectly for contributors that would like to have their first contribution to an open-source project.
47+
48+
How to find issues with `good first issue` label:
49+
50+
1. The easiest way is to go into the `github.com/<owner>/<repository>/contribute` link. In this case, you can go into [this link](https://github.com/WhiteClover4/SecondHand-FE/contribute). That link will list all of the issues with the `good first issue` label.
51+
2. Another way is to head over into the [Issues](https://github.com/WhiteClover4/SecondHand-FE/issues) section of the repository, then click the Labels section beside Milestones. There you can see a lot of labels for the issues in the repository. Then find and click the `good first issue` label.
52+
53+
### Working on issues
54+
55+
#### Getting ready
56+
57+
Before working on an issue, please make sure to:
58+
59+
1. Fork the repo properly. Even you have done it before, it's still advised that you read / skim [the official guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository).
60+
2. Clone **your forked repository** and set it up by following the [Getting Started guide](https://github.com/WhiteClover4/SecondHand-FE#getting-started).
61+
3. Check any open [pull requests](https://github.com/WhiteClover4/SecondHand-FE/pulls) that no one is working on the issue.
62+
4. Create a new branch from the `main` branch.
63+
64+
#### Issue assignment & Communication
65+
66+
Once you're ready with your branch and have something to contribute, you'll want to
67+
let everyone know that you are working on the issue. To communicate this, we
68+
are using GitHub's Draft Pull Requests.
69+
70+
Draft Pull Request is like a regular Pull Request but it can't be merged until
71+
it's marked as "ready for review". It signals other contributors that [it's a
72+
work in progress](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request).
73+
This is necessary to signal other contributors that the work for the particular
74+
issue has started and it is still in progress. Also, it is a better approach to
75+
use as a communication tool between contributors because we can provide
76+
additional information other than viewing the changed files.
77+
78+
Therefore, when you have at least one commit **it's important to create a Draft
79+
Pull Request** to let everyone know that the issue is assigned to you.
80+
81+
#### Creating a Draft Pull Request
82+
83+
Steps to creating a Draft Pull Request:
84+
85+
1. Commit and push your new changes into the remote repository. Please refer to [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional) for your commit message or you can use [commitlint.io](https://commitlint.io/) to assist you in composing the commit message.
86+
2. Head over to the Pull requests section on your forked repository, hit New pull request.
87+
![Hint-1](https://user-images.githubusercontent.com/46013258/126284390-c2bd1aa6-fdc2-4aa6-a945-031f02db038e.png)
88+
3. Pick your forked repository for the head repository, and compare with the branch that you are having changes in.
89+
![Hint-2](https://user-images.githubusercontent.com/46013258/126285036-27b49325-62a2-4a6c-b216-5bae261788da.png)
90+
4. Put a clear title and description in your pull request. Make sure the
91+
description follows [our guide below](#formatting-pull-request-description).
92+
![Hint-3](https://user-images.githubusercontent.com/46013258/126286179-04341e30-1224-49cb-9b9a-3c3aee99c308.png)
93+
5. Pick Create draft pull request (like in the image above) and hit the green button.
94+
6. Don't forget to mark your Draft Pull Request as Ready for review after you commit all of the changes.
95+
96+
#### Formatting Pull Request Description
97+
98+
To properly [link a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue), there is one tiny requirement text to put in a Pull Request description.
99+
Please make sure to mention the issue that you're working on correctly. Replace
100+
this text `<!-- mention the issue that you're trying to close with this PR -->`
101+
from the template with the issue number. Example:
102+
103+
```markdown
104+
Closes #318
105+
106+
## Description
107+
108+
Update **`Start working on Issues`** section with clearer instructions on getting ready to work on an issue.
109+
```
110+
111+
### Disabling GitHub Actions
112+
113+
We recommend contributors to disable GitHub action on your forked repository.
114+
115+
1. Go to Setting on your forked repository
116+
2. Choose Action on sidebar
117+
3. Disable Actions
118+
![Disable-actions](https://user-images.githubusercontent.com/35433920/129485485-ca7d1202-5dbc-46f7-b823-978d3f4ed600.png)
119+
120+
## FAQ
121+
122+
### Why are we using English in our issues & PRs?
123+
124+
There are several reasons we're using English while communicating in GitHub Issues & PRs:
125+
126+
1. It's more natural for software engineers to communicate in English because it involves many technical terms in English. Trying to translate them into Bahasa Indonesia posing a risk of miscommunication, while keeping them in English requires us to do a lot of _italic_ formatting, according to [PUEBI](https://puebi.js.org/huruf/miring).
127+
2. It accustoms the contributors, which are mostly Indonesian, to communicate in English. It is important to increase our English reading and writing skills because the vast majority of the global open-source communities are using Engish as the main language.
128+
3. It makes this project easier to be recognised globally. So if we need to get more support from the global communities, they could easily understand what we are doing and help us out with their access and competence. e.g., providing us free credits for their services, advocating us to global leaders, or contributing directly to our codebase.
129+
130+
## Additional Notes
131+
132+
### Commitlint
133+
134+
In a repository with many contributors like this, it's important to understand
135+
what's going on in it and navigate between commits. Moreover, with various
136+
levels of contributors & their backgrounds, the commit messages can easily be
137+
confusing and the structure may follow different approaches.
138+
139+
To overcome these issues, the maintainers adopt [commit conventions](https://www.conventionalcommits.org/en/)
140+
to allow contributors to add more semantic meaning to our git history. They use
141+
[commitlint](https://commitlint.js.org/) to lint the git commit messages.
142+
To enforce the conventions, the maintainers use a git hook to run the
143+
commitlint upon a git commit command. The git hook prevents the commit the
144+
staged files if the commit message failed to comply with the conventions.
145+
146+
It's adviseable to read the [commit conventions](https://www.conventionalcommits.org/en/v1.0.0)
147+
briefly to further understand the other benefits from them. However, if you're
148+
having problems with it, you can use [this
149+
tool](https://commitlint.io/) to help.
150+
151+
Furthermore, please refer to the list of [commit types](#commit-types) and
152+
[scopes](#commit-scopes) that we use to avoid adding a new scope that has similar
153+
meaning or is synonym to the existing one.
154+
155+
## References
156+
157+
### Conventional Commits
158+
159+
The convention specification looks like this:
160+
161+
```
162+
<type>[optional scope]: <description>
163+
164+
[optional body]
165+
166+
[optional footer(s)]
167+
```
168+
169+
#### Commit types
170+
171+
Here are what we use for the commit types:
172+
173+
- `build`
174+
- `chore`
175+
- `docs`
176+
- `feat`
177+
- `fix`
178+
- `perf`
179+
- `refactor`
180+
- `style`
181+
- `test`
182+
183+
#### Commit scopes
184+
185+
Here are what we use for the scopes:
186+
187+
- `assets`
188+
- `ci`
189+
- `cms`
190+
- `components`
191+
- `donasi`
192+
- `education`
193+
- `home`
194+
- `json-ld`
195+
- `kontak-darurat`
196+
- `layout`
197+
- `telemedicine`
198+
- `cypress`
199+
- `deps`
200+
- `dx`
201+
- `e2e`
202+
- `fetcher`
203+
- `pages`
204+
- `faq`
205+
- `isoman`
206+
- `security`
207+
- `seo`
208+
- `ui`
209+
210+
**Note:** If there's a second level in a list, only the lowest level gets to be used.
211+
212+
### Issue and Pull Request Labels
213+
214+
Issue labels are a tool to group issues into one or more categories.
215+
It helps us track and manage issues and pull requests.
216+
217+
Please open an issue on [`WhiteClover4/SecondHand-FE`](https://github.com/WhiteClover4/SecondHand-FE) if you have suggestions for new labels.
218+
219+
#### Type of Issue and Issue State
220+
221+
| Label name | `/SecondHand-FE.` | Description |
222+
| ------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
223+
| `blocked` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/blocked) | Issues blocked by something else. |
224+
| `bug` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/bug) | Confirmed bugs or reports that are very likely to be bugs. |
225+
| `enhancement` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/enhancement) | New feature or request. |
226+
| `epic` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/epic) | A master issue thread which contains other smaller issues. |
227+
| `good first issue` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/good%20first%20issue) | Less complex issues which would be good first issues to work on for users who want to contribute to SecondHand-FE. |
228+
| `help wanted` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/help%20wanted) | Issue that need extra attention. |
229+
| `invalid` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/invalid) | Issues which aren't valid (e.g. user errors). |
230+
| `question` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/question) | More information needs to be collected about these problems or feature requests (e.g. steps to reproduce). |
231+
| `wontfix` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/wontfix) | The SecondHand-FE team will not fix these issues for now. |
232+
233+
#### Topic Categories
234+
235+
| Label name | `/SecondHand-FE.` | Description |
236+
| ----------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
237+
| `ci-cd` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/ci-cd) | Continuous Integration & Continuous Delivery. |
238+
| `design` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/design) | Issue related to design. |
239+
| `documentation` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/documentation) | Improvements or additions to documentation. |
240+
| `dx` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/dx) | Developer Experience. |
241+
| `ui` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/ui) | User interface. |
242+
| `ux` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/ux) | User experience. |
243+
| `seo` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/seo) | Search engine optimization. |
244+
| `scripting` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/scripting) | Issue related to the code. |
245+
| `testing` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/testing) | Automated testing. |
246+
| `netlify-cms/draft` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/netlify-cms%2Fdraft) | Draft for content changes in Netlify CMS. |
247+
| `netlify-cms/pending_publish` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/netlify-cms%2Fpending_publish) | Content changes ready to be published through Netlify CMS. |
248+
| `netlify-cms/pending_review` | [search](https://github.com/WhiteClover4/SecondHand-FE/labels/netlify-cms%2Fpending_review) | Content changes pending review in Netlify CMS. |

0 commit comments

Comments
 (0)