feat: add readme info (#51)

* feat: add readme info

* fix: linting and spelling

* fix: spelling errors and bot if statement

* chore: add link and tidy text

* fix: markdown linting error

.github/workflows/project_board_automation.yml

@@ -12,7 +12,7 @@ name: 'Project board automation'
   pull_request_review_comment:
     types: [created]
 
-# Configure the project specific varaibles
+# Configure the project specific variables
 env:
   ORGANIZATION: theteamworks
   PROJECT_NUMBER: 3
@@ -57,7 +57,7 @@ jobs:
 
       - name: 'Check if PR raised by bot'
         id: bot-pr
-        if: ${{ github.actor == 'dependabot[bot]' }}
+        if: contains('refs/heads/dependabot/', github.ref)
         uses: actions/github-script@v6.1.0
         with:
           github-token: ${{secrets.GITHUB_TOKEN}}

README.md

@@ -1,31 +1,55 @@
 
-# project-board-automation
+# GitHub Project Board Automation
 
-An action that will automate the movement of the cards on a GitHub projects(beta) board.
+An action that will automate the movement of the issues or pull requests on a GitHub projects(beta) board.
 
-Done as GraphQL queries to be faster than building a GitHub Action.
+Before thinking of using this check out the following info and understand the assumptions made and the context it was designed for.
 
-> ℹ️ Info: This is some informational text.
+- The [Rationale](./docs/Rationale.md) for doing this
+- The [Process](./docs/Rationale.md) the team should be following
+- The [Detailed Workflow](./docs/Workflow.md) diagram of the action
+- The [GitHub Settings](GitHubSettings.md) that are required
+- The [Project Board](https://github.com/orgs/theteamworks/projects/3) will have columns as per this example (column names can be changed).
 
-Blocks need text between them. So remember.
+This has been done using GitHub Action `run` and GraphQL queries to be faster than building a full GitHub Action. This is because this action will run often and this action runs in 5-10 seconds.
 
-> ⚠️ Warning: This is a warning notification.
+## Setting up the action
 
-```python
+This has been designed for a non-developer person to copy a file, configure a few settings and have the board automated. Obviously the team needs to understand and buy into the process, albeit a lightweight one.
 
-if __name__ == '__main__':
-    main()
+### Copy the yaml file
 
-```
+Copy the GitHub Action [yaml file](https://github.com/theteamworks/project-board-automation/blob/main/.github/workflows/project_board_automation.yml) from this repository to get the latest version. Tagged versions with release notes and known issues will be created periodically. Copy this file into your repository in the same location `.github/workflows/`.
+
+### Configure the action
+
+The action requires a few organisation and project settings to be configured:
 
-## Set up the action
+```yaml
+
+# Configure the project specific variables
+env:
+  ORGANIZATION: theteamworks
+  PROJECT_NUMBER: 3
+  PR_URL: ${{ github.event.pull_request.html_url }}
+  GITHUB_TOKEN: ${{ secrets.BOARD_AUTOMATION }}
+  EXCLUDE_LABEL: 'no-issue'
+  IN_PROGRESS_COLUMN_NAME: '"IN_PROGRESS"'
+  REVIEW_REQUIRED_COLUMN_NAME: '"REVIEW_REQUIRED"'
+  IN_REVIEW_COLUMN_NAME: '"IN_REVIEW"'
+  APPROVED_COLUMN_NAME: '"APPROVED"'
+  MERGED_COLUMN_NAME: '"MERGED"'
+  DONE_COLUMN_NAME: '"DONE"'
+  ITERATION_FIELD_NAME: Iteration   # See project settings (default is `Iteration`)
+
+```
 
-To configure the GitHub Action...
+#### Exclusion label
 
-## Set up the (beta) project board
+In order for the action to know that the pull request does not require the mandate of a planned issue (as per the [no issue required](./docs/Process.md###pull-requests-with-no-issue-required) process) an exclusion label needs to be defined.
 
-To configure the GitHub board setting in a columns...
+This label must be configured in the yaml file and also be present in each of the repositories that the work on the project board may come from.
 
-## Set up branch protection
+## Dependabot
 
-To configure the GitHub branch protection... Testing.
+> ℹ️ Info: This action has not been fully working with dependabot pull requests and is the subject of further testing. Happy path has been tested.

docs/GitHubSettings.md

@@ -0,0 +1,15 @@
+# GitHub Settings
+
+## Branch protection rules
+
+These were the key branch protection rules enabled for this automation to work as intended. Its advisable to look at all the other settings as some are highly recommended.
+
+<img src="./image/require-pull_request_approvals.png"/>
+
+<img src="./image/require-pull_request_approvals.png"/>
+
+## Token permissions
+
+These were the token permissions enabled for this automation to work as intended. It's advisable to review these to ensure all are indeed required as this could impact security.
+
+<img src="./image/token_permissions.png"/>

docs/Process.md

@@ -2,22 +2,36 @@
 
 In order to use this the team will need to follow this process. The intention is that this is as process-light as it can be for the development team when developing complex software products.
 
-## Guiding principals
+## Guiding principles
+
+No one wants to waste time updating the board, everyone knows there is value in an accurate view on work being done.
 
 ### Planning with Issues
 
-### Tasks (Pull requests) with no issues
+Its assumed that with this board automation the team is working with some planning process. Be it a Kanban style replenishment, or a Scrum type sprint planning; the team has the notion of a `todo` column and picks work items from this list to work on.
+
+### Pull requests with no issue required
+
+There are always exceptions to planned items, items may be so small that the overhead of creating issues and linking pull requests is both a waste of time and money.
+
+In the event of a `crasher` type bug where work may be done immediately, or a minor refactor or fix, it's well understood that a no-issue pull request may be the best option.
+
+In this case raise a pull request and add the configured [exclusion label](./README.md#configure-the-action) and continue the work and the PR will be added to the board and move as per the issue would.
 
 ### Use the review process in GitHub
 
-### Pick a card from `TODO` and add your name(s) to it
+This workflow has been set up around a flow that requires a pull request to merge into your `main` / `develop` branch. It also works with `CODEOWNERS` and any number of reviews-required before being approved to merge. The GitHub repository settings can be seen [here](./GitHubSettings)
+
+### Pick a card from `todo` and add your name(s) to it
 
 Follow:
 
-1. Pick a card from `TODO`
+1. Pick a card from `todo`
 1. Add your name(s) to it (pairing is cool)
-1. Work on your pull request (draft, reviews, changes, merge)
-1. Board is updated automatically
-1. Move to `Done` after we deploy (don't let this column get too big).
+    - if you forget linking a pull request or adding the exclusion label will add the item to the board
+1. Work on your pull request as you would (draft -> reviews -> changes -> merge)
+1. Voila, the board is updated automatically from `in-progress` to `merged`
+1. Keep an eye on column lengths (WIP limits) to avoid starting more than you finish
+1. Manually move the items `Done` after they have been deployed (don't let this column get too big - Aargh; big batch releases!).
 
 Bingo!

docs/Rationale.md

@@ -1,7 +1,9 @@
 # Rationale
 
-The reason I have is because:
+The reason for this is because:
 
 1. In most cases developers/testers do not want to be bogged down with remembering to update the project board
-2. It is important for the status of work items to be transparent for other team members, stakeholders, managers, sponsors etc.. to see whats happening
+2. It is important for the status of work items to be transparent for other team members, stakeholders, managers, sponsors etc.. to see what's happening
 3. In order to manage flow (keep WIP in check so throughput doesn't plummet) we need to see everything that has been started.
+
+It's also designed for a non-developer (me) to be able to add a yaml file to a repository, change a few configurations and automate their team's board.

docs/Workflow.md

@@ -0,0 +1,5 @@
+# Workflow
+
+This diagram shows the detailed flow diagram:
+
+<img src="./image/board_automation.drawio.svg"/>

docs/image/board_automation.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2022-06-07T12:04:05.394Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" etag="f8JLGJocPIcCBSBqtrcy" version="18.1.1" type="device"><diagram id="ZqQHE2ktCwA6-DW3dVe1" name="Page-1">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</diagram></mxfile>

wordlist.txt

@@ -1,4 +1,13 @@
+Aargh
 Changelog
+env
 GitHub
+github
 GraphQL
-WIP
+html
+Kanban
+organisation
+theteamworks
+url
+WIP
+yaml