GitHub Issues and Discussions
Better open science development through communication
What are Issues?
GitHub Issues are a tool that allows users to create, discuss, and track work in a repository:
Tracking: Use issues to track tasks, bugs, ideas, and feedback
Collaboration: Use issues to collaborate on ideas and tasks
Communication: Use issues to communicate with others
Planning: Use issues to plan and track work
What are Discussions?
GitHub Discussions are a collaborative communication forum for the community around an open source or internal project:
Share announcements and information
Plan and make decisions with community input
Encourage and answer questions, and mark them answered as you respond to them
Gauge community opinion using polls
When to use Issues vs Discussions
Issues: specific, actionable items
Discussions: Q&A, triage bugs, transparent conversations about broader vision
Issues can spin off of discussions
Anatomy of an Issue
https://github.com/nmfs-opensci/GitHub-Clinic-demos/issues/7
Title: simple but descriptive
Description: issue context
Task lists: break work into smaller tasks, track progress
Reprex: bare minimal example of the issue
Assignees: who is responsible for the issue
Labels: categorize and prioritize issues
Projects: link issues to project boards
Milestones: track progress towards a goal
Development: link issues to code changes
Other Issue features
Markdown: use markdown language features like headings, lists, links, code chunks, and images
Mentions: type @ in an issue description or comment to ping a collaborator
Link issues: type # and part of an issue title to link out to a related issue
Sub-issues: add nested issues within an overarching broader issue
Issue types and templates
Different kinds of repositories need different kinds of issue templates.
Blank issue: standard, blank issue for things that don’t fall under other templates
Bug report: bring attention to a bug or problem in the repo
Feature request: ideas for improvements or additions to a repo
Issue types and templates
Different kinds of repositories need different kinds of issue templates.
Questions: general question about the repository (may be better for Discussion)
Tasks: tasks and project management related to the repository (generally reserved for development team)
Custom templates: tailored to needs of the team
Discussion types and templates
Similarly, there are different kinds of Discussion templates for different purposes
Announcements: updates from maintainers
General: equivalent of a blank issue; general chat
Ideas: discuss new features you would like to see
Polls: take a vote from developers and users
Q&A: ask the community for help
Show and tell: showcase a new feature or use case
Issues and discussions etiquette
Search for your issue prior to submitting a new one
Use the right forum (issues vs discussions)
Use templates if provided
Provide minimal reproducible examples
Use mentions sparingly
