Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
[WIP] Mentor notification fix issue#3881 #393
This makes the link in the mentor notification mailer point to a student's most recent iteration and adds a test to the code.
Background: Previously, when a student submitted a solution, mentors were notified with a link to their solution. However if the student submitted a new iteration, the link was for an earlier iteration.
The test looks sensible in terms of structure, but it's testing for the wrong link, and the code that makes it pass is therefore also wrong.
I wanted to give feedback on a meta topic here.
When working on a small team, it's sometimes OK to submit a pull request with no description and a title that alludes to what the PR is about, because everyone on the team has context about what is being worked on.
In open source, that's typically not well-received, as open source projects are large, sprawling, have thousands of people involved, most of whom do not have context about what's going on everywhere in the project.
The TL;DR of pull requests is this:
The pull request should stand alone.
In more detail, here are some high-level thoughts about pull requests:
The reviewer should be able to understand the purpose of the pull request, the problem being solved, and why you approached it in the way you did, without looking at other issues and pull requests.
The title should summarize the change that is being made.
Also part of the pull request is the various tabs. I typically look at how many commits there are, how many files changed, and how many lines changed to get a sense of the size of the pull request.
Here the pull request is not too daunting, with only 4 lines added and one removed. Sometimes I need to review a pull request with hundreds of lines that have changed, in which case I will put it off. A lot.
One thing to notice is that when you reference the issue in the title, it doesn't link anywhere. This means that the reviewer has to guess what you're fixing. If we manually construct the link to issue 3881 in this repository, it gives us a 404, because the issue isn't in this repository (this repo doesn't have issues, and I happen to know that the issue is in exercism/exercism, but in a project with many repositories, links should link directly to what you're referencing).
So not only does the maintainer have to guess what problem "mentor notification fix" is, they also have to expend effort figuring out where the problem is described. Asking maintainers to do extra, unnecessary work does not provide the best first impression. They're going to be somewhat less charitable than if you did your utmost to make this a smooth PR for them to review.
You should link to things, but not from the title, since those links aren't clickable. Any link should be clickable, and correct.
Here's a great guide for how to write a pull request when working in the context of a company:
Much of it is relevant to open source, with the caveat that in open source you should typically not mention specific people or teams, unless the person you are mentioning is someone you know well. For example, I will often mention Jeremy when dealing with core Exercism stuff, or Wilken when working on the exercism/cli repository.
I think it would be worth your time to watch this video, which does a really good job of summarizing what a great PR looks like from the perspective of an overworked and overburdened open source maintainer: https://www.youtube.com/watch?v=u2xzRUYrsWA