Skip to content

Commit

Permalink
Fixes hackforla#511
Browse files Browse the repository at this point in the history
  • Loading branch information
@ruben1s
ruben1s committed Jul 12, 2020
1 parent 8224256 commit 31efef8
Showing 1 changed file with 257 additions and 0 deletions.
257 changes: 257 additions & 0 deletions _guide-pages/github-issues.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,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>
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'
---



<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">Copy</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"></span>Developers: </span><br>
- <br>
- <br>
</code>
</div>
</div>
</div>


<!-- <div class="section-container">
<h3 id="member-analytics">Member Analytics</h3>
</div> -->


<script>

const issueTemplate = document.querySelector('.issue-template-code');
const code = document.querySelector('.template-code');
const copyButton = document.querySelector('.copy-button');

copyButton.addEventListener("click", copyText);

function copyText() {
issueTemplate.focus();
document.execCommand("selectAll");
const text = code.value;
document.execCommand("copy");
copyButton.style.border = "0.5px solid #7A7A7A";
copyButton.style.boxShadow = "inset 0px 0px 6px rgba(0, 0, 0, 0.39)";
}
</script>

0 comments on commit 31efef8

Please sign in to comment.