search

philip-gai / announcement-drafter

A bot for drafting and publishing GitHub discussions using pull requests.
https://github.com/apps/announcement-drafter
ISC License
12 stars 2 forks source link

Onboard @Cameron-Gai #97

Closed philip-gai closed 1 year ago

philip-gai commented 2 years ago

Onboarding for @Cameron-Gai.

Context

What is Announcement Drafter?

Announcement Drafter is a GitHub App.

GitHub Apps

GitHub apps are basically integrations that can get installed on GitHub repositories (repos). GitHub Apps subscribe to "events" that happen in GitHub, such as:

When these events happen, GitHub sends a POST web request to the GitHub App, and the GitHub App receives that request and can do whatever it wants with it.

Here's a simple example of a what a GitHub app can do:

  1. Subscribe to "issue assigned" events on a GitHub repo
  2. When an issue is assigned in that repo, GitHub sends the POST request to the GitHub App API server
  3. The GitHub App receives the request, which includes all the information about the event - what repo it happened on, what issue it relates to, and who was assigned
  4. The app then writes a comment on the issue the event came from: @<user-who-was-assigned>, you have been assigned to this issue!

As you can imagine, you can go crazy and make the GitHub App do almost anything you want it to do.

So what does Announcement Drafter do?

GitHub has something called Discussions. It's basically where developers can discuss any topic related to the repository the discussion takes place in.

People use discussions to make announcements of new releases, features, etc. But there's one problem - you can't draft a discussion. So there's no way to privately share your discussion post for a teammate to review it.

Enter Announcement Drafter 🙂

GitHub has the concept of pull requests (PRs). A pull request is basically the way a developer submits code to be merged into the main branch of the repository. A developer makes a change to the code, and proposes that it makes it into the main version of the code via a pull request. Others on the project then see the pull request and review the code. They make comments, suggestions, and discuss ways to improve the code. After several reviews and iterations, once everyone agrees the code acceptable, the reviewers approve the PR and it gets merged into the main branch.

So GitHub uses pull requests to gather feedback on code from teammates. Why can't we use them for gathering feedback on discussions? After all, a discussion is written in markdown, which is essentially code for documentation. (This issue is actually written in markdown!)

That's what announcement drafter is. You write your discussion (announcement) in a markdown file in the repo and create a pull request to get it reviewed. Once it's reviewed and approved, you merge it and announcement drafter automatically copies the markdown and creates the discussion where you tell it to.

Things to Know

There are some technologies and concepts that are helpful to know to be effective working on this project.

This GitHub App is written in Typescript and is deployed as an Azure Web App.

Here's a checklist of things to get familiar with, you can just go down the list in order and read the linked material.

Once you've read and done those tutorials, explore the code in this repo.

Now, when you're ready, I can help you get your development environment setup and give you a good first issue to work on!

Cameron-Gai commented 1 year ago

Still looking to give this a try eventually. I'm still not ready