[llvm][github] Add good-first-issue comment to issues

[tbaeder]

Summary

Try adding a "good first issue" comment to github issues with that label, welcoming new contributors and listing a few first steps.

I think the actual comment needs some work, I wasn't sure if the steps I outlined can't be improved.

Also, the patch is completely untested since I'm not sure how I would test it at all.

[tbaeder]

Something along the lines of "do not ask to work on an issue, if it is unassigned, you can start working on it" might be useful in the text as well...

[tstellar]

In D146819#4229626, @tbaeder wrote:

Something along the lines of "do not ask to work on an issue, if it is unassigned, you can start working on it" might be useful in the text as well...

I think asking people to assign the issue to themselves when working on it would make sense.

[tbaeder]

In D146819#4231709, @tstellar wrote:

In D146819#4229626, @tbaeder wrote:

Something along the lines of "do not ask to work on an issue, if it is unassigned, you can start working on it" might be useful in the text as well...

I think asking people to assign the issue to themselves when working on it would make sense.

I actually had this as step 1 of the instructions, no idea why it's not there anymore. I'll add it back.

[aaron.ballman]

Thank you for working on this, I think it's a really good idea! One issue I see with it though is that the GitHub issues list is used by multiple projects (llvm, clang, lldb, libc++, etc) but the way in which you contribute to these projects differ. So I think these instructions will work great for most folks, but we may want to consider the other projects and whether we need to adjust any wording here accordingly. (Personally, I think any project within the monorepo that diverges from the usual policies sufficiently enough to cause problems like this should either consider moving out of the monorepo or changing their policies to be in line with the rest of the monorepo, but that's a much bigger discussion than this patch. I think this patch kind of demonstrates why those policy differences cause friction for new contributors.)

llvm/utils/git/github-automation.py

34

Do we want to link to https://clang.llvm.org/docs/ClangFormat.html#git-integration around here?

36

38

Given that Phabricator may be unknown to folks new to the community, do we also want to add a link to https://llvm.org/docs/Phabricator.html somewhere in here or do we think the contributing guide should suffice?

[tbaeder]

In D146819#4233226, @aaron.ballman wrote:

Thank you for working on this, I think it's a really good idea! One issue I see with it though is that the GitHub issues list is used by multiple projects (llvm, clang, lldb, libc++, etc) but the way in which you contribute to these projects differ. So I think these instructions will work great for most folks, but we may want to consider the other projects and whether we need to adjust any wording here accordingly. (Personally, I think any project within the monorepo that diverges from the usual policies sufficiently enough to cause problems like this should either consider moving out of the monorepo or changing their policies to be in line with the rest of the monorepo, but that's a much bigger discussion than this patch. I think this patch kind of demonstrates why those policy differences cause friction for new contributors.)

Right, I was thinking the script could be more sophisticated and e.g. check that any of the labels are of the "clang:" kind - and then post clang-specific instructions, and do the same for lld, libc++, etc. but that's just not an exact science.

If these instructions are a problem for any of the subprojects, we can still iterate on them. Should I maybe add someone from lld/lldb/libc++/etc. to the CC here?

[aaron.ballman]

In D146819#4238098, @tbaeder wrote:

In D146819#4233226, @aaron.ballman wrote:

Thank you for working on this, I think it's a really good idea! One issue I see with it though is that the GitHub issues list is used by multiple projects (llvm, clang, lldb, libc++, etc) but the way in which you contribute to these projects differ. So I think these instructions will work great for most folks, but we may want to consider the other projects and whether we need to adjust any wording here accordingly. (Personally, I think any project within the monorepo that diverges from the usual policies sufficiently enough to cause problems like this should either consider moving out of the monorepo or changing their policies to be in line with the rest of the monorepo, but that's a much bigger discussion than this patch. I think this patch kind of demonstrates why those policy differences cause friction for new contributors.)

Right, I was thinking the script could be more sophisticated and e.g. check that any of the labels are of the "clang:" kind - and then post clang-specific instructions, and do the same for lld, libc++, etc. but that's just not an exact science.

If these instructions are a problem for any of the subprojects, we can still iterate on them. Should I maybe add someone from lld/lldb/libc++/etc. to the CC here?

From what I've seen on the issues list for Clang, most of the time the person filing the issue is not the person adding labels to the issue. Instead, someone triaging the issues list sees there's a "new issue" label on something and they remove it and add the appropriate labels, including "good first issue".

So I think that maybe we should reword Thank you for your interest in working on this LLVM issue. into This issue may be a good introductory issue for people new to working on LLVM. If you would like to work on this issue, your first steps are: or something along those lines?

But this also points out that perhaps basing the text on labels is not going to work consistently; it's not uncommon to add "good first issue" before adding e.g., "lldb" and so it's reasonably possible we'd generate the text before we know the final set of labels on the issue.

[aaron.ballman]

The text bits LGTM, but I leave it to @tstellar for final approval given this is for github automation.

[tstellar]

LGTM.

llvm/utils/git/github-automation.py

 import github
 import os
 import re
 import requests
 import sys
 import time
 from typing import List, Optional
 
+beginner_comment =
+"""
+Hi!
+
+This issue may be a good introductory issue for people new to working on LLVM. If you would like to work on this issue, your first steps are:
+
+  1) Assign the issue to you.
+  2) Fix the issue locally.
+  3) [Run the test suite](https://llvm.org/docs/TestingGuide.html#unit-and-regression-tests) locally.
+    3.1) Remember that the subdirectories under `test/` create fine-grained testing targets, so you can
+         e.g. use `make check-clang-ast` to only run Clang's AST tests.
+  4) Create a `git` commit
+  5) Run [`git clang-format HEAD~1`](https://clang.llvm.org/docs/ClangFormat.html#git-integration) to format your changes.
+  6) Submit the patch to [Phabricator](https://reviews.llvm.org/).
+    6.1) Detailed instructions can be found [here](https://llvm.org/docs/Phabricator.html#requesting-a-review-via-the-web-interface)
+
+For more instructions on how to submit a patch to LLVM, see our [documentation](https://llvm.org/docs/Contributing.html).
+
+If you have any further questions about this issue, don't hesitate to ask via a comment on this Github issue.
+"""
+
 class IssueSubscriber:
 
     @property
     def team_name(self) -> str:
         return self._team_name
 
     def __init__(self, token:str, repo:str, issue_number:int, label_name:str):
         self.repo = github.Github(token).get_repo(repo)
         self.org = github.Github(token).get_organization(self.repo.organization.login)
         self.issue = self.repo.get_issue(issue_number)
         self._team_name = 'issue-subscribers-{}'.format(label_name).lower()
 
     def run(self) -> bool:
         for team in self.org.get_teams():
             if self.team_name != team.name.lower():
                 continue
-            comment = '@llvm/{}'.format(team.slug)
+
+            comment = ''
+            if team.slug == 'issue-subscribers-good-first-issue':
+                comment = '{}\n'.format(beginner_comment)
+
+            comment += '@llvm/{}'.format(team.slug)
             self.issue.create_comment(comment)
             return True
         return False
 
 def setup_llvmbot_git(git_dir = '.'):
     """
     Configure the git repo in `git_dir` with the llvmbot account so
     commits are attributed to llvmbot.