-
-
Notifications
You must be signed in to change notification settings - Fork 777
/
github-issues.html
257 lines (213 loc) · 12.7 KB
/
github-issues.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
---
title: Getting the Most Out of GitHub Issues
description: Each of Hack for LA’s GitHub project repositories (repos) use <a href="https://guides.github.com/features/issues/">issues</a> to track and organize ideas, enhancements, and tasks. All team members will use GitHub issues to communicate in our multifunctional teams. <br><br> When creating a new GitHub issue, the following tips will help you provide consistent formatting, a clear and concise overview, actionable tasks, explanatory resources, and resumé items to add value for all volunteers. <br><br> <em>All GitHub Issues use <strong>markdown</strong> for formatting. View GitHub’s <a href="https://guides.github.com/features/mastering-markdown/">Mastering Markdown</a> for a simple guide.</em>
short-description: Each of Hack for LA’s GitHub project repositories (repos) use issues to track and organize ideas, enhancements, and tasks. All team members will use GitHub issues to communicate in our multifunctional teams.
in-this-guide:
- name: Example of a Good End-to-End Issue
link: '#example-issue'
- name: Issue Sections - Description and Tips
link: '#issue-sections'
- name: Issue Template
link: '#issue-template'
- name: Member Analytics
link: '#member-analytics'
card-type: guide-page
status: work-in-progress
display: true
practice-area: Development
tools:
- GitHub
contributors:
- Danielle Nedivi
- Bonnie Wolfe
source: Hack for LA
recommended-by:
svg: /assets/images/toolkit-default-card-image.png
resource-url-completed: '/guide-pages/github-issues'
resource-url-wip:
resource-url-depreciated:
---
<div class="section-container link-section">
<h3 id="example-issue">Example of a Good End-to-End Issue</h3>
<h5>An effective Hack for LA Github issue includes the following components:</h5>
<p><em>Click any section link below to jump down to its description</em></p> <br>
<div class="overlay-links">
<img class="screenshot" src="../assets/images/guides/github-issue/good-issue-example.svg" >
<!-- Arrows and Overlay Text Links -->
<!-- RIGHT SIDE LINKS -->
<img class="assignees" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#assignees-section" class="assignees">ASSIGNEES</a></h4>
<img class="labels" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#labels-section" class="labels">LABELS</a></h4>
<img class="project-board" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#project-board-section" class="project-board">PROJECTS</a></h4>
<img class="milestones" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#milestones-section" class="milestones">MILESTONES</a></h4>
<!-- LEFT SIDE LINKS -->
<img class="title left-pointer" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#title-section" class="title">TITLE</a></h4>
<img class="overview left-pointer" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#overview-section" class="overview">OVERVIEW</a></h4>
<img class="dependency left-pointer" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#dependency-section" class="dependency">DEPENDENCY</a></h4>
<img class="action-items left-pointer" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#action-items-section" class="action-items">ACTION ITEMS</a></h4>
<img class="resources left-pointer" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#resources-section" class="resources">RESOURCES/ INSTRUCTIONS</a></h4>
<img class="resume left-pointer" src="../assets/images/guides/pink-pointer.svg">
<h4><a href="#resume-section" class="resume">RESUME</a></h4>
</div>
<p><em>This issue is shown in Preview mode</em></p>
</div>
<div class="section-container">
<h3 id="issue-sections">Issue Sections: Descriptions and Tips</h3>
<h5>Follow the recommendations below to create a useful end-to-end GitHub issue</h5>
<p class="subheading"><em>You can either format with <a href="https://guides.github.com/features/mastering-markdown/">markdown</a> text manually or using the text box toolbar</em></p><br>
<h4 id="title-section">TITLE</h4>
<p>
Describe what you’re working on — <br><br>
For a start-to-finish issue, as in this case, choose a title that is generic enough to allow for all phases (research, ideation, design, development). <br><br>
For an issue taking on only part of the workflow, be more declarative in what it covers (e.g. a research issue might be called “Determine Best Testing Library for Code Base”).
</p><br>
<img src="../assets/images/guides/github-issue/issue-sections-1.png"><br>
<img src="../assets/images/guides/gray-arrow.svg" class="grayarrow"><br>
<img src="../assets/images/guides/github-issue/issue-sections-2.png"><br><br><br><br>
<h4 id="overview-section">OVERVIEW</h4>
<p>Clearly state the purpose of this issue in 2 lines or less.</p>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-3.png">
<p class="img-caption">Markdown draft: ### formats header</p>
</div><br>
<img src="../assets/images/guides/gray-arrow.svg" class="grayarrow"><br>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-4.png"><br>
<p class="img-caption">Final post</p>
</div><br><br><br>
<div class="inline-text-with-title"><h4 id="dependency-section">DEPENDENCY </h4>
<span> (if applicable)</span></div>
<p>If your issue relies on another issue’s completion first, link to the issue it is dependent on.</p>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-5.png">
<p class="img-caption">Markdown draft: [title](url) formats links</p>
</div><br>
<img src="../assets/images/guides/gray-arrow.svg" class="grayarrow"><br>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-6.png">
<p class="img-caption">Final post</p>
</div><br><br><br>
<h4 id="action-items-section">ACTION ITEMS</h4>
<p>
Formatted as a clickable checklist. <br><br>
If this is the beginning of the task, this is most likely something to be researched and documented. <br><br>
When the research is complete, what will happen next? Describe the steps in your checklist (broadly, if the research will change the details). <br><br>
If the steps can be divided into tasks for more than one person, we recommend dividing it up into separate sections.
</p><br>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-7.png">
<p class="img-caption">Markdown draft: - [ ] formats checklist</p>
</div><br>
<img src="../assets/images/guides/gray-arrow.svg" class="grayarrow"><br>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-8.png">
<p class="img-caption">Final post</p><br>
</div><br>
<img src="../assets/images/guides/gray-arrow.svg" class="grayarrow"><br>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-9.png">
<p class="img-caption">Final post with checkmarks</p>
</div><br><br><br>
<h4 id="resources-section">RESOURCES / INSTRUCTIONS</h4>
<p>
If there is a link with documentation that helps with this issue, provide the link(s) here.
</p><br>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-10.png">
<p class="img-caption">Markdown draft</p>
</div><br>
<img src="../assets/images/guides/gray-arrow.svg" class="grayarrow"><br>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-11.png">
<p class="img-caption">Final post</p>
</div><br><br><br>
<h4 id="resume-section">RESUME</h4>
<p>
Specify how tasks can be listed in all assignees’ resumés to provide value for project volunteers, divided by roles.
</p><br>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-12.png">
<p class="img-caption">Markdown draft</p>
</div><br>
<img src="../assets/images/guides/gray-arrow.svg" class="grayarrow"><br>
<div class="img-and-caption">
<img src="../assets/images/guides/github-issue/issue-sections-13.png">
<p class="img-caption">Final post</p>
</div><br><br><br>
<h4 id="assignees-section">ASSIGNEES</h4>
<p>
Select assignees to clarify who is working on specific issues and pull requests.<br><br>
In the upper-right corner, click Assignees. To assign a user (including yourself), start typing their username and click their name when it appears. <br><br>
Assign the issue to only one person at a time, by order of their tasks.
</p><br>
<span><img src="../assets/images/guides/github-issue/issue-sections-14.png">
<img src="../assets/images/guides/github-issue/issue-sections-15.png"></span><br><br><br>
<h4 id="labels-section">LABELS</h4>
<p>
Select all relevant labels. See GitHub’s <a href="https://help.github.com/en/github/managing-your-work-on-github/about-labels">About Labels</a> guide for more details.
</p><br>
<span><img src="../assets/images/guides/github-issue/issue-sections-16.png">
<img src="../assets/images/guides/github-issue/issue-sections-17.png"></span><br><br><br>
<h4 id="project-board-section">PROJECT BOARD</h4>
<p>
Make sure your issue is added to your team’s Project Board, and properly triaged. Click <a href="https://help.github.com/en/github/managing-your-work-on-github/adding-issues-and-pull-requests-to-a-project-board#adding-issues-and-pull-requests-to-a-project-board-from-the-sidebar">here</a> to learn more. <br><br>
If the issue has been created but is not ready to assign, it should be set in the <strong>ice box.</strong><br><br>
If the issue has been created and is ready but not yet assigned to someone, it should be set in <strong>prioritized backlog.</strong><br><br>
When someone has been assigned to the issue, this should be set to <strong>in progress.</strong>
</p><br>
<img src="../assets/images/guides/github-issue/issue-sections-18.png"><br><br><br>
<h4 id="milestones-section">MILESTONES</h4>
<p>
You can use milestones to track the progress of groups of issues or pull requests in a repository. Read more at GitHub’s <a href="https://help.github.com/en/github/managing-your-work-on-github/about-milestones">About Milestones</a> guide.
</p><br>
<img src="../assets/images/guides/github-issue/issue-sections-19.png"><br><br><br>
<div class="inline-text-with-title"><h4 class="black-font ">TIP: </h4><h4> PREVIEW</h4></div>
<p>
Don’t forget to preview your new issue before posting to make sure it’s formatted correctly.
</p><br>
<img src="../assets/images/guides/github-issue/issue-sections-20.png"><br><br><br>
</div>
<div class="section-container">
<h3 id="issue-template">Issue Template</h3>
<p>Copy/paste the following <a href="https://guides.github.com/features/mastering-markdown/">markdown</a> template text into your new GitHub issue and fill out using the guidelines above.</p><br>
<div class="issue-template-container" >
<button class="copy-button"><img src="../assets/images/guides/clipboard.png" class="clipboard"> <span class="copy-button-text">Copy</span></button>
<div class="issue-template-code" contenteditable="true" spellcheck="false">
<code class="template-code">
### Overview <br>
<br>
### Action Items <br>
- [ ] <br>
- [ ] <br>
- [ ] <br>
<br>
### Resources/Instructions <br>
<span class="blue-text">[link title](link URL)</span><br>
<br>
### Resume <br>
<br>
<span class="green-text">UX Writing: </span><br>
- <br>
- <br>
<span class="green-text">UI Mockup: </span><br>
- <br>
- <br>
<span class="green-text">Developers: </span><br>
- <br>
- <br>
</code>
</div>
</div>
</div>
<!-- <div class="section-container">
<h3 id="member-analytics">Member Analytics</h3>
</div> -->
<script src="../assets/js/elements/copyButton.js"></script>