Skip to content

Commit 03a0a4d

Browse files
samgutentagsamgutentag
authored
Write a HIP in Browser Guide (helium#1347)
* Write a HIP Guide * remove leftover edit blurb
1 parent 7d595a3 commit 03a0a4d

17 files changed

+287
-2
lines changed

‎docs/faq/edit-a-hip.mdx

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,17 @@ This page will walk users through the process of:
2828

2929
---
3030

31+
### Markdown Formatting
32+
33+
All HIPs in the Helium GitHub repository are written in Markdown an easy-to-read, easy-to-write
34+
syntax for formatting plain text. Read more about basic writing and formatting syntax
35+
[here.](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
36+
37+
Do not let knowledge of Markdown stop you from writing a proposal. Get words on a page, and the
38+
repository maintainers and other community members will help!
39+
40+
---
41+
3142
## Fork the Repo
3243

3344
**Step 1.** Log in to an existing account or create a new account on [GitHub](https://github.com).

‎docs/faq/write-a-hip.mdx

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
---
2+
id: write-a-hip
3+
title: Propose a New HIP
4+
pagination_label: Propose a New HIP
5+
sidebar_label: Propose a New HIP
6+
description: Helium Documentation
7+
image: https://docs.helium.com/img/link-image.png
8+
slug: /write-a-hip
9+
---
10+
11+
import useBaseUrl from '@docusaurus/useBaseUrl'
12+
13+
While HIPs are in discussion the actual text is included in the
14+
[Helium HIP Repository on GitHub](https://github.com/helium/hip).
15+
16+
Before a HIP goes to a vote, changes and revisions will likely need to be made to an existing
17+
proposal.
18+
19+
:::tip Key Take Aways
20+
21+
This page will walk users through the process of:
22+
23+
- Creating a personal copy, or "fork", of the Helium HIP repository.
24+
- Copying the HIP template.
25+
- Writing a new proposal using the in-browser text editor.
26+
- Submitting the proposal for review.
27+
28+
:::
29+
30+
---
31+
32+
### Markdown Formatting
33+
34+
All HIPs in the Helium GitHub repository are written in Markdown an easy-to-read, easy-to-write
35+
syntax for formatting plain text. Read more about basic writing and formatting syntax
36+
[here.](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
37+
38+
Do not let knowledge of Markdown stop you from writing a proposal. Get words on a page, and the
39+
repository maintainers and other community members will help!
40+
41+
---
42+
43+
## Fork the Repo
44+
45+
**Step 1.** Log in to an existing account or create a new account on [GitHub](https://github.com).
46+
47+
**Step 2.** Open the Helium HIP Repository at
48+
[https://github.com/helium/hip](https://github.com/helium/hip)
49+
50+
**Step 3.** Click the `Fork` button in the upper right-hand corner.
51+
52+
<figure className="screensnippet-wrapper">
53+
<img
54+
src={useBaseUrl('/img/hip/fork-step-0.png')}
55+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
56+
/>
57+
</figure>
58+
59+
<br />
60+
61+
**Step 4.** Leave all settings default and confirm using the green `Create Fork` button at the
62+
bottom left-hand corner.
63+
64+
<figure className="screensnippet-wrapper">
65+
<img
66+
src={useBaseUrl('/img/hip/fork-step-1.png')}
67+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
68+
/>
69+
<figcaption>
70+
A copy of the Helium HIP repository will be made in the user's GitHub account and should open
71+
automatically.
72+
</figcaption>
73+
</figure>
74+
75+
---
76+
77+
## Write a New HIP
78+
79+
All HIPs follow a consistent format as closely as possible for their content. To get authors
80+
started, a [template](https://github.com/helium/HIP/blob/main/0000-template.md) has been provided in
81+
the HIP repository under the filename `0000-template.md`.
82+
83+
**Step 1.** Open the HIP template in a second window with this link:
84+
85+
[https://raw.githubusercontent.com/demogutentag/HIP/main/0000-template.md](https://raw.githubusercontent.com/demogutentag/HIP/main/0000-template.md)
86+
87+
<figure className="screensnippet-wrapper">
88+
<img
89+
src={useBaseUrl('/img/hip/write-step-0.png')}
90+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
91+
/>
92+
<figcaption>Keep this window open, or open the URL in an additional tab.</figcaption>
93+
</figure>
94+
95+
<br />
96+
97+
**Step 2.** In the primary window, click the `Add file` button in the upper right-hand corner and
98+
select `Create new file` from the dropdown.
99+
100+
<figure className="screensnippet-wrapper">
101+
<img
102+
src={useBaseUrl('/img/hip/write-step-1.png')}
103+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
104+
/>
105+
</figure>
106+
107+
<br />
108+
109+
**Step 3.** Give your file a name, the recommended format is `0000-my-new-proposal.md` replacing the
110+
`my-new-proposal` with a relevant title to the proposal itself.
111+
112+
<figure className="screensnippet-wrapper">
113+
<img
114+
src={useBaseUrl('/img/hip/write-step-2.png')}
115+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
116+
/>
117+
<figcaption>
118+
This example creates a proposal to never give up on the Helium Network and never let it down and
119+
is named `0000-astley-incentive.md`
120+
</figcaption>
121+
</figure>
122+
123+
<br />
124+
125+
**Step 4.** Copy and paste the contents of the page from Step 2 to start.
126+
127+
<figure className="screensnippet-wrapper">
128+
<img
129+
src={useBaseUrl('/img/hip/write-step-3.png')}
130+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
131+
/>
132+
<figcaption>
133+
If you have been authoring a proposal in another location, copy and paste it here, adjusting to
134+
fit the template structure.
135+
</figcaption>
136+
</figure>
137+
138+
<br />
139+
140+
**Step 5.** Click the green `Commit changes...` button in the upper right-hand corner.
141+
142+
<figure className="screensnippet-wrapper">
143+
<img
144+
src={useBaseUrl('/img/hip/write-step-3b.png')}
145+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
146+
/>
147+
</figure>
148+
149+
<br />
150+
151+
**Step 6.** In the pop-up window, select the
152+
`Create a new branch for this commit and start a pull request` option.
153+
154+
<figure className="screensnippet-wrapper">
155+
<img
156+
src={useBaseUrl('/img/hip/write-step-4.png')}
157+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
158+
/>
159+
</figure>
160+
161+
<br />
162+
163+
**Step 7.** Click the Green `Propose changes` button.
164+
165+
<figure className="screensnippet-wrapper">
166+
<img
167+
src={useBaseUrl('/img/hip/write-step-5.png')}
168+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
169+
/>
170+
</figure>
171+
172+
<br />
173+
174+
**Step 8.** Do not click the green `Create pull request` button on this page. Click the grey `Code`
175+
tab.
176+
177+
<figure className="screensnippet-wrapper">
178+
<img
179+
src={useBaseUrl('/img/hip/write-step-6.png')}
180+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
181+
/>
182+
</figure>
183+
184+
<br />
185+
186+
---
187+
188+
## Make a Pull Request
189+
190+
A Pull Request, or "PR", is quite literally an ask to the repository maintainers to "pull in"
191+
proposed changes.
192+
193+
**Step 1.** A new banner will be presented with a green `Compare & pull request` button. Click the
194+
button to start a Pull Request
195+
196+
<figure className="screensnippet-wrapper">
197+
<img
198+
src={useBaseUrl('/img/hip/write-step-7.png')}
199+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
200+
/>
201+
</figure>
202+
203+
<br />
204+
205+
**Step 2.** Confirm the Pull Request is to the `helium/HIP` base `main` and the correct changes are
206+
being proposed.
207+
208+
<figure className="screensnippet-wrapper">
209+
<img
210+
src={useBaseUrl('/img/hip/write-step-8.png')}
211+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
212+
/>
213+
</figure>
214+
215+
<br />
216+
217+
**Step 3.** Edit the `Title` and `Description` to inform other readers and maintainers what the HIP
218+
is about.
219+
220+
<figure className="screensnippet-wrapper">
221+
<img
222+
src={useBaseUrl('/img/hip/write-step-9.png')}
223+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
224+
/>
225+
<figcaption>
226+
Copy and pasting the Summary from the proposal itself is a good `Description` filler.
227+
</figcaption>
228+
</figure>
229+
230+
<br />
231+
232+
**Step 4.** Click the green `Create pull request` button.
233+
234+
<figure className="screensnippet-wrapper">
235+
<img
236+
src={useBaseUrl('/img/hip/write-step-10.png')}
237+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
238+
/>
239+
</figure>
240+
241+
<br />
242+
243+
**Step 5.** View the newly created Pull Request in the main Helium HIP repository.
244+
245+
<figure className="screensnippet-wrapper">
246+
<img
247+
src={useBaseUrl('/img/hip/write-step-11.png')}
248+
style={{ maxHeight: 800, borderRadius: '40px', padding: '14px 16px 20px' }}
249+
/>
250+
</figure>
251+
252+
<br />
253+
254+
---
255+
256+
## Stay Involved
257+
258+
Once a PR is submitted, authors are asked to keep a watch on them for comments or change requests.
259+
By default, the user to submit a PR will be subscribed via email to receive notifications on PR
260+
activity.
261+
262+
Timely responses in GitHub and Discord keep the process moving!

‎docusaurus.config.js

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,11 @@ module.exports = {
7373
label: 'Governance',
7474
position: 'left',
7575
},
76+
{
77+
to: '/hotspot-makers',
78+
label: 'Hospot Makers',
79+
position: 'left',
80+
},
7681
{
7782
to: '/devblog',
7883
label: 'Dev Blog',

‎sidebarsDocs.js

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -183,13 +183,20 @@ module.exports = {
183183
link: { type: 'doc', id: 'governance/governance' },
184184
items: [
185185
'governance/voting',
186-
'governance/hip',
187186
'governance/realms',
188187
'governance/working-groups',
189188
'governance/committees',
190-
'faq/edit-a-hip',
191189
],
192190
},
191+
{
192+
type: 'category',
193+
label: 'Improvement Proposals',
194+
link: { type: 'doc', id: 'governance/hip' },
195+
items: ['faq/write-a-hip', 'faq/edit-a-hip'],
196+
},
197+
],
198+
199+
hotspotmakers: [
193200
{
194201
type: 'category',
195202
label: 'Manufacturer Conformance Committee ',

‎static/img/hip/write-step-0.png

547 KB
Loading

‎static/img/hip/write-step-1.png

688 KB
Loading

‎static/img/hip/write-step-10.png

476 KB
Loading

‎static/img/hip/write-step-11.png

550 KB
Loading

‎static/img/hip/write-step-2.png

457 KB
Loading

‎static/img/hip/write-step-3.png

635 KB
Loading

‎static/img/hip/write-step-3b.png

636 KB
Loading

‎static/img/hip/write-step-4.png

671 KB
Loading

‎static/img/hip/write-step-5.png

668 KB
Loading

‎static/img/hip/write-step-6.png

491 KB
Loading

‎static/img/hip/write-step-7.png

650 KB
Loading

‎static/img/hip/write-step-8.png

472 KB
Loading

‎static/img/hip/write-step-9.png

478 KB
Loading

0 commit comments

Comments
 (0)