From fd5ebfc551f00eca7fdfdd98379ee738e7bfb0a5 Mon Sep 17 00:00:00 2001 From: Ethan Davidson <31261035+EthanThatOneKid@users.noreply.github.com> Date: Mon, 15 Nov 2021 23:48:03 -0800 Subject: [PATCH] Added documentation for v2.0 workflows (#222) * Added documentation for v2.0 workflows * Update CONTRIBUTING.md * Updated grammar/formatting in the related docs --- .github/workflows/update_officer.yaml | 5 ++++- CONTRIBUTING.md | 29 +++++++++++++++++++++++++++ scripts/close-issue-channel.js | 10 +++++---- 3 files changed, 39 insertions(+), 5 deletions(-) diff --git a/.github/workflows/update_officer.yaml b/.github/workflows/update_officer.yaml index da9c332e3..2696fb688 100644 --- a/.github/workflows/update_officer.yaml +++ b/.github/workflows/update_officer.yaml @@ -48,8 +48,11 @@ jobs: with: commit-message: Updated officer data title: 'Add/Update officer ${{ steps.officer-name.outputs.result }}' - body: Resolves \#${{ github.event.issue.number }} ✨ branch: 'automation/${{ github.event.issue.number }}' + body: | + This PR was automatically generated by our [`update_officer.yaml`](https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/.github/workflows/update_officer.yaml) workflow. For more info, see [`CONTRIBUTING.md`](https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/CONTRIBUTING.md#creating-an-officer-update-request). + + Resolves \#${{ github.event.issue.number }} ✨ - name: Close Issue id: close_successfully diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 35f838838..0a57ffbf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,6 +72,35 @@ Notice that the value `768px` is constant. The next most common breakpoint for larger desktop screens would be `1440px`. Really, the situation may affect your choice of breakpoint value, but the goal is to try to use only `768px` or `1440px` wherever possible for consistency-purposes. +## Custom Workflows + +In this repository, we use GitHub Actions to _automate all the things_ 😎 + +### Creating an Officer Update Request + +To update the way an officer appears on , contributors may fill out our [**Officer Update Request Form**](https://github.com/EthanThatOneKid/acmcsuf.com/issues/new?assignees=&labels=automation%3Aofficer&template=officer_update_request.yaml&title=%5BOFFICER_AUTOMATION%5D) ([source](https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/.github/ISSUE_TEMPLATE/officer_update_request.yaml)) to automate a pull request with the requested changes. +Contributors are free to merge the auto-generated pull request if it seems to have made the intended changes. + +The [`workflows/update_officer.yaml`](https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/.github/workflows/update_officer.yaml) workflow configuration automates each time an issue is opened with the `automation:officer` label. +This workflow relies on [`scripts/update-officer.js`](https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/scripts/update-officer.js) to make the appropriate changes to the checked-out codebase (including updating the repo's `officers.json` file or adding/replacing their image in the repo's `/static/assets/authors/` directory). +Then, the workflow generates a pull request based on the changes made by the `update-officer.js` script and immediately closes the issue. + +### Automated Third-Party Message Board + +Our team uses Discord as our third-party messaging service of choice to discuss relevant topics that aren't suited/ready for GitHub. +We have text channels set up on Discord dedicated to every open issue on GitHub. +This approach allows us to communicate about multiple issues in an orderly and stress-free fashion. + +Manually creating and closing text channels for every single GitHub issue is not an appropriate solution to this problem since the text channels will eventually become stale. +We also want a way to archive these discussions without cluttering the Discord server with text channels. +To accomplish these needs, we need a way to automate those tasks whenever an issue is created or closed on this GitHub repository. + +The [`workflows/create_issue_channel.yaml`](https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/.github/workflows/create_issue_channel.yaml) workflow is responsible for creating a new text channel whenever an issue is opened [or reopened] on Github. +This workflow relies on [`scripts/create-issue-channel.js`](https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/scripts/create-issue-channel.js) to create the text channel and send the first message containing a link to the newly created issue. + +The [`workflows/close_issue_channel.yaml`](https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/.github/workflows/close_issue_channel.yaml) workflow is responsible for closing a text channel whenever a corresponding issue is closed [or deleted] on Github. +This workflow relies on [`scripts/close-issue-channel.js`](https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/scripts/close-issue-channel.js) to transcribe the old issue channel's messages to a dedicated _archive_ channel and then delete the old channel. + ## Webmaster's Note 📝 Thank you for contributing! diff --git a/scripts/close-issue-channel.js b/scripts/close-issue-channel.js index 1140ef921..4fb55e988 100644 --- a/scripts/close-issue-channel.js +++ b/scripts/close-issue-channel.js @@ -11,9 +11,9 @@ startBot(async (client) => { }); /** - * # Close Issue Channel Script + * ### Close Issue Channel Script * - * ## Command Line Usage + * #### Command Line Usage * * 1. Make sure your environment variables are defined. * 1. Run the following command. @@ -22,7 +22,7 @@ startBot(async (client) => { * node scripts/close-issue-channel.js 180 * ``` * - * ## GitHub Workflow Usage + * #### GitHub Workflow Usage * * ```yaml * - run: node scripts/close-issue-channel.js ${{ github.event.issue.number }} @@ -32,7 +32,9 @@ startBot(async (client) => { * ARCHIVE_CHANNEL_ID: ${{ secrets.ARCHIVE_CHANNEL_ID }} * ``` * - * See `.github/workflows/close_issue_channel.yaml`. + * --- + * + * See https://github.com/EthanThatOneKid/acmcsuf.com/blob/main/.github/workflows/close_issue_channel.yaml. */ const closeIssueChannel = async (client, issueNumber, dev = false) => { let success = false;