Using Issues for Feedback


(Vanessa) #1

Issues for feedback

Professional software developers use issues and pull requests to get meaningful feedback about their work and to track their progress on projects. Educators can help students do it too!

Git and GitHub give developers a bunch of ways to share their work, like pushing to branches, forking repositories, and opening issues and pull requests. But with so many ways to use those tools, it can be difficult for students and other new developers to learn how to use them effectively.

Luckily, GitHub has a bunch of guardrails, like issue and pull request templates, labels, project boards, and saved replies, that can help guide developers into productive planning and discussion. Not only can these tools be used by instructors to give students feedback, but they can also be used to help students learn important communication and project planning skills.

Preparing a repository

When you’re creating a repository that your students might work from, you’ll probably include things like starter code, tests, or a a README file with assignment details. But did you know you can also include templates for the issues students may need to create to plan a new feature or write a useful bug report?

If you’ve never used them before, issue templates provide starter text when creating a new issue in GitHub. An issue template can give students (and educators alike) guidance about how to write an issue, often with fill in the ____ text, a checklist, or common questions to answer. Instead of staring down the blank canvas of an empty issue comment box, students can get a running start at writing.

Issue templates are Markdown files that are stored in the repository’s .github/ISSUE_TEMPLATE directory. Because they’re part of the repository like any other file tracked by Git, they persist across forks and are included when you use them as an assignment repository in GitHub Classroom. Later, when your students go to create issues on the repository, they’ll see something like this:

Similarly, pull request templates can guide students to describe what changes their pull request makes and to help them make sure they’ve included all the required pieces.

Students have issues

Equipped with issue and pull request templates, students can organize themselves and their work. Your students might begin by creating issues for major components of their assignment. For group assignments, they might assign issues to specific students. For larger or long-running projects, students might even copy a project board to help them plan out the work.

As groups of students work, they might open pull requests, using templates in their repository to guide their writing. Then other members of the project team join in with discussion or review comments, providing peer feedback. When the students reach consensus, they can merge the pull request and move on to the next task on their project board.

Instructors give feedback

Before too long, it’ll be the instructor’s turn to chime in on their students’ work. When the students are finished or reach a milestone, the instructor can take advantage of the same tools as their students, to highlight accomplishments and encourage improvements.

For example, if students have submitted, reviewed, and merged a pull request, an instructor can provide follow-up comments or line-by-line code review. Instructors can do the same with issue comments, to give students feedback on multiple levels, from assessment of design to choices to team workflow and communication.

Instructors can also reflect the software development process in their feedback by giving their feedback in the form of new issues or pull requests. For example, an instructor might discover a bug in their students’ work and file an issue against the repository describing the problem. This not only gives students feedback, but also models the practice of writing issues. A similar approach can be used with pull requests.

If all that sounds like a lot of writing, you’re probably right! But you can save time by using GitHub’s saved replies. If you find yourself making similar comments on students’ work, you can save text that you can reuse in comments on issues and pull requests—they appear in the upper right corner of the editor

You can even use saved replies when starting an issue or pull request, which is a handy shortcut when the repository you’re working with doesn’t have issue or pull request templates yet. Of course, feedback templates themselves will save an instructor time and serve as a reminder to students about the grading rubric for the assignment.

How do you give feedback within GitHub.com?

Even with the support of GitHub’s communications tools, there’s still lots of ways to give students feedback about their work. How do you do it?