Basic Issues - psu-libraries/library_data_services GitHub Wiki

Github issues is pretty easy but with some extra bells and whistles that make it potentially very powerful. There are really just seven moving parts.

1. Issue Number

This is assigned automatically, but can be used to link this issue to other things. For instance, linking to other issues that this issue depends on.

2. Title

This is just the title of the issue. Make it informative and succinct.

3. Description

This describes the issue. You can use **Markdown** to format it as well.

4. Comments

This is where any discussion of the issue goes. Once you comment on an issue, you get emails about further comments.

5. Labels

These are a convenient way of tagging issues for a variety of reasons. The labels can be topical (i.e. describe the subject), procedural (i.e. describe the stage in a workflow the issue is in), categorical (i.e. if its a question, suggestion or error), or really anything. Labels can quickly get out of hand, here is a link to one businesses way of [handling labels](https://robinpowered.com/blog/best-practice-system-for-organizing-and-tagging-github-issues/) that gives a good practical way of thinking about them.

6. Milestones

These are essentially calendar based labels. They are great for setting due dates and timelines for groups of issues.

7. Assignee(s)

This is the person primarily responsible for the issue. Often there will be more than one person working on an issue, but you are only allowed one assignee. In this case, just have other participants comment on an issue, and they will become participants.

As always with great power, comes great responsibility. In this context, I've found that Github issues are so flexible, that it can easily become a mess without some community standards. Also, just about everything in Github works with Markdown (Github flavored Markdown). Here is a cheatsheet to get you started. I also just look at how other things have been written OR google what I want to do, I've never not found an answer. There is also usually a link at the button of an issue that will bring you to the Mastering Markdown page. Markdown is actually pretty easy.

1. Go to the Issues tab and click the green New Issue button.
2. Give it a title. If you are doing this yourself just name it "Testing" or something.
3. Provide a description. Any text will be fine. Its in Markdown so you can format it.
4. Give it labels (please give it a testing label).
5. Give it a milestone. You can create a testing milestone if you want.
6. Assign yourself or me (Rob O.). If you assign me, I'll get an email, but that is fine.
7. Submit the Issue.

Normally you would comment on an issue rather than edit it, especially if you weren't the author. Common practice is to only edit issues or comments for clarity. Your edits are versioned as well, so don't worry too much about them. For anything more than a small change, comments are preferred. Sometimes previous entries will be edited in light of comments.

1. Open an issue.
2. Edit the description or comment you wish.
3. Add a comment.
4. Click the green Comment button.

Issues are closed when it seems the discussion is ended, or if the work associated with the issue is complete. It is common practice to give a reason why the issue is closed. Also, for work related issues, often only the product owner actually closes the issue.

Closed an issue by accident? Not a problem, just reopen it.

1. Click the Close button or Close and Comment button.