Tracking with GitHub Issues

1. What are GitHub Issues?

Think of GitHub Issues as a dedicated project management and discussion forum built right into your repository. They are the starting point for almost all work. While the name might suggest they are only for "issues" or bugs, they are used for a much wider range of purposes:

• Bug Reports: Detailing unexpected behavior.
• Feature Requests: Proposing new functionality.
• Tasks: Tracking a to-do list for a larger goal.
• Questions & Discussions: A place to ask for clarification or discuss ideas before writing any code.

In a DevOps context, this creates a transparent and traceable workflow. A feature can be proposed in an Issue, discussed by the team, implemented in a branch, reviewed via a Pull Request that references the original Issue, and finally deployed, with the entire history linked together.

2. The Anatomy of an Issue

Creating an issue is straightforward, but creating an effective one requires providing the right information. Let's look at the core components and the basic workflow.

The video below provides an excellent demonstration of creating, assigning, and labeling an issue.

As you saw, every issue has several key parts:

• Title: A concise summary of the task.
• Description: A detailed explanation. You can use Markdown to format text, add images, create lists, and more.
• Assignees: The person or people responsible for working on the issue.
• Labels: Tags used to categorize issues. Common default labels include bug, enhancement, documentation, and good first issue. Teams often create custom labels for priority (priority:high), status (status:in-progress), or team ownership (team:backend).

3. Best Practices: Writing Clear and Actionable Issues

An issue with the title "It's broken" and no description is not helpful. To work effectively, especially in a distributed team, issues must be clear, concise, and contain all the necessary information for someone to understand the task and start working on it.

To summarize the key best practices:

• For a Bug Report:
  • Title: Start with "Bug:" followed by a clear summary.
  • Steps to Reproduce: Provide a numbered list of the exact steps to trigger the bug.
  • Expected vs. Actual Behavior: State what you thought would happen and what actually happened.
  • Environment: Include relevant details like Operating System, Browser/Version, etc.
  • Evidence: Add screenshots, error messages, or log files.
• For a Feature Request:
  • Title: Start with "Feature:" or "Enhancement:".
  • Problem Statement: Describe the problem this feature would solve ("As a user, I want to... so that I can...").
  • Proposed Solution: Describe how you imagine the feature working.

4. Linking Code to Issues: The Magic of Integration

The real power of GitHub Issues comes from their tight integration with code. You can link your commits and pull requests directly to the issues they address, creating a complete audit trail.

The same video we watched earlier demonstrates this powerful feature.

There are two key takeaways here:

1. Referencing an Issue: Simply include #<issue-number> (e.g., #42) in a commit message or pull request description. GitHub will automatically convert this into a link to the issue.
2. Auto-Closing an Issue: Use keywords like closes, fixes, or resolves before the issue number (e.g., fixes #42). When a commit or PR with this message is merged into the repository's default branch (usually main), GitHub will automatically close the corresponding issue. This is an incredibly efficient workflow for DevOps.

5. Leveling Up: Issue Templates

To ensure everyone on the team follows the best practices we just discussed, you can create Issue Templates. These are pre-filled templates for different types of issues (like bugs or features) that prompt the author to provide specific information.

Setting up templates involves creating Markdown files in a special .github/ISSUE_TEMPLATE directory in your repository. This is a common DevOps task to help standardize project workflows.

6. Practical Exercise: Managing Work with Issues

Let's use the pr-practice repository from our last lesson to put this all into practice. If you deleted it, please create a new repository.

Step 1: Create a Bug Report Issue

1. Navigate to your pr-practice repository on GitHub and click the "Issues" tab.
2. Click "New issue".
3. For the Title, enter: Bug: Project description is missing from README.
4. In the Description, write a proper bug report. Use the following structure:

   **Steps to Reproduce:**
   1. Clone the repository.
   2. Open the `README.md` file.
   
   **Expected Behavior:**
   The README should contain a title and a brief description of the project's purpose.
   
   **Actual Behavior:**
   The README only contains a title. There is no project description.
   

5. On the right-hand side, under Labels, select the bug label. If it doesn't exist, create it.
6. Under Assignees, assign the issue to yourself.
7. Click "Submit new issue". Note the issue number (it will likely be #1).

Step 2: Create a Feature Request Issue

1. Click "New issue" again.
2. For the Title, enter: Feature: Add a contribution guide.
3. In the Description, write:

   To encourage others to contribute, we should add a `CONTRIBUTING.md` file that explains how to participate in the project.
   

4. Under Labels, select the enhancement label.
5. Assign this issue to yourself as well.
6. Click "Submit new issue".

Step 3: Fix the Bug and Link the Work

1. On your local machine, cd into your pr-practice directory. Make sure you are on the main branch and have the latest changes (git pull origin main).
2. Create a new branch to fix the bug: git checkout -b fix/readme-description.
3. Open README.md in an editor and add a description line. The file should look like this:

   # PR Practice Project
   This project is for practicing the GitHub pull request and code review workflow.
   

4. Stage and commit the change. This is the important part! Write a commit message that will auto-close the issue. Replace #1 with your actual bug report issue number.

   git add README.md
   git commit -m "docs: Add project description to README
   
   This commit adds the missing project description to the main README file, addressing the identified bug.
   
   Fixes #1"
   

5. Push your branch to GitHub: git push origin fix/readme-description.

Step 4: Create and Merge the Pull Request

1. Go to GitHub. You should see a prompt to create a pull request for your new branch. Click it.
2. The title and description will be pre-filled from your commit message. Notice on the right sidebar under "Development," your PR is already linked to the issue!
3. Click "Create pull request".
4. Since this is a simple fix, you can immediately click "Merge pull request" and then "Confirm merge".

Step 5: Verify the Result

1. Go back to the "Issues" tab.
2. You should see that the bug report issue is now in the "Closed" section.
3. Click on the closed issue. You will see a notification in the timeline stating that you closed this issue via the commit you just merged.

Conclusion

You have now learned to manage the entire lifecycle of a task in GitHub, from inception to completion. Issues provide the "what" and "why," while branches and pull requests provide the "how."

Key Takeaways:

• GitHub Issues are used to track bugs, features, and other tasks.
• A high-quality issue has a clear title, a detailed description (with steps to reproduce for bugs), and appropriate metadata like labels and assignees.
• You can reference an issue in a commit or PR with #<issue-number>.
• You can automatically close an issue by using keywords like fixes, closes, or resolves in your commit message when it's merged into the default branch.
• Issue templates help enforce consistency and quality across your project.

In our next lesson, we will tie all of this together by looking at structured workflows for development. Now that we know how to track tasks (Issues) and manage code changes (PRs), we'll explore different branching strategies like GitFlow and GitHub Flow to organize how we build features and fix bugs in a systematic way.