After completing this page, you will be able to:
In the previous lesson, you learned about how pull requests can be used to suggest changes to a project. These pull requests not only clearly document your changes, they also allow for collaborators to review the changes and discuss things, prior to them being merged into the main project repo. In this lesson you will learn about issues. Issues can be used to drive or define the content of pull requests. This type of tracking makes managing a GitHub project with multiple collaborators easier and more efficient.
In this lesson we are using the open source model of software contribution as a basis for the workflow that we are describing.
What is a GitHub Issue?
Issues in GitHub are text based descriptions of things that need to be addressed, changed or worked in a project or GitHub repo. GitHub issues can help you manage a collaborative project that you are working on with others. All that you need to create an issue on GitHub is a GitHub login. Issues are written in plain text using Markdown to format the content of the issue.
GitHub issues are an excellent way to keep track of bugs and other items that need to be addressed in a project.
GitHub issues can be used to identify and track:
- Bugs or problems with code in your repo. For example
this thingdoesn’t work as expected.
- Things that are missing in your repo. For example perhaps something isn’t documented correctly.
- Enhancements or new functionality that is needed in the code.
- Documentation updates.
- General questions and discussion points that need to be considered by all collaborators
- and more…
TODO: ADD GOOD CAPTION TO ABOVE. it could be nice to create a really precise list of issues as an example. could be used in the class. Talk with Jenny about this!
GitHub Issues Can Be Used to Manage Collaborative Projects and To Allow Both Coders and Non Coders to Contribute to a Project
GitHub issues are a way that anyone can identify problems with the code in your project. Not everyone is a programmer or a coder. But sometimes people are using your code and have questions, or find bugs. Issues are a way for others to contribute, regardless of their technical expertise.
Use GitHub Issues To Manage Working Being Done On Your Project Through Pull Requests
While you can submit a pull request (PR) at any time, it’s best practice to consider starting a change to a repo using an issue. To begin, submit the issue.
… more here …
- Make The Issue Name Descriptive: It’s helpful to have descriptive issue titles that tell the code owners what the issue is about. Descriptive titles become particularly important if there are many issues in a repo.
- Create an Reproducible Code Example (If it’s a code bug): If your issue is about a bug in the code, it’s going to be easiest to understand if the code owners can reproduce the bug. Provide some code that someone can copy and run and see the exact bug that you are seeing.
Mention Specific People Using @github-username-here
- Question: create new page for following or add to this page:
- Communicate with @mention
- Using Issues
- Create a new issue
- Close an issue through a pull request
About Pull Requests
- Need to save copies of all external images using file-names-like-this.png to images/earth-analytics/git-version-control
- Move all images that need it to images/earth-analytics/git-version-control