README.md

Announcement Drafter

A 🤖  for drafting and publishing new GitHub discussions using pull requests.

Do you use GitHub discussions? Do you create announcements for your open-source projects or team posts? How do you get feedback or peer reviews on your post before creating it?

Now you can:

    1️⃣  Create a pull request to get feedback from your teammates on your announcement
    2️⃣  Merge the pull request to have your announcement posted!

You can even use private repos to draft announcements and get feedback privately, and on merge have the announcement created in your public repo.

No more copy/pasting your post content into Google Docs. No more rewriting the markdown. Write the markdown once, get feedback and merge 🚀 This works on repository discussions, organization discussions, and legacy team posts.

Getting Started

1. Install the GitHub App and authorize it for any repositories or orgs you would like it to watch or post to.

2. Add a .github/announcement-drafter.yml (not .yaml) configuration file to any repositories you want the bot to watch.

   1. Provide what folders you want the announcement-drafter bot to watch and (optionally) what folders you would like it to ignore when new pull requests are open.

   watch_folders:
     - docs/discussions/

3. Create a markdown (*.md) file with some metadata at the top - see Draft an Org or Repository Discussion or Draft a team post

4. Write your discussion in the body of the markdown file

5. Create a pull request

6. announcement-drafter will pick it up

7. When the pull request is merged, it will create the discussion for you

Draft an Org or Repository Discussion

A note on org discussions: Org discussions are backed by repository discussions, so just point to the repository used by your org discussions and 🪄 it will work!

<!--
repo: https://github.com/philip-gai/announcement-drafter-demo
category: announcements
-->

<!-- This is the discussion title -->
# Hello World! 👋

<!-- This is the discussion body -->
Hello beautiful world! 🌎

Draft a Team Post

<!--
team: https://github.com/orgs/elastico-group/teams/everyone
-->

<!-- This is the post title -->
# Hello World! 👋

<!-- This is the post body -->
Hello beautiful world! 🌎

Demos

Demo repo: announcement-drafter demo

Markdown Metadata

Name	Description	Required	Example
repository or repo	The full url to the repository to create the discussion in Prerequisites:   1. Discussions are enabled   2. The app is installed on the repo	Conditional: Required if no team is provided	https://github.com/philip-gai/announcement-drafter-demo
team	The full url to the team to create the discussion in Prerequisites:   1. The app is installed on the team organization	Conditional: Required if no repository is provided	https://github.com/orgs/elastico-group/teams/everyone
category	The name of the discussion category	Conditional: Required if repository is provided	announcements
Discussion Title	The title of your discussion should be the first top-level header (i.e. # Discussion Title)	Yes	See Example
Discussion Body	The body of your discussion is everything after the top-level header	Yes	See Example

App Configuration Options

These options should go in your repository's .github/announcement-drafter.yml file.

Name	Description	Required	Example
watch_folders	A list of what folders (relative paths) announcement-drafter should watch when new pull requests are open   1. It is recommened to include the final / in the path   2. announcement-drafter will also watch all subfolders unless you ignore them in ignore_folders	Yes	See demo config
ignore_folders	A list of what folders (relative paths) announcement-drafter should ignore when new pull requests are open	No	See demo config

Example announcement-drafter.yml:

watch_folders:
  - docs/discussions/
ignore_folders:
  - docs/discussions/ignore/

FAQ

I opened a pull request, but I never received a comment on the pull request from Announcement Drafter. What did I do wrong?

Make sure that you:

1. Installed the app on the repository you created the pull request from
2. Added a .github/announcement-drafter.yml file to the repository with watch_folders
3. Created a new *.md file inside one of the watch_folders from a branch
   1. Announcement Drafter will only process files that were added. It will not process files that were removed, modified, renamed, copied, changed or unchanged.
4. Opened a pull request targeting the repository's default branch (i.e. main)
   1. Announcement Drafter will ignore draft pull requests

Also, try closing and re-opening your PR after making any changes to the announcement drafter configuration to trigger the flow again.

If you followed all of the above steps and are still experiencing issues, please open an issue 🙂

Contributing

If you have suggestions for how announcement-drafter could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

For more, check out the Contributing Guide.