From 442e7fb17d3ecc7e36c7d4a7a383f1d42b535df3 Mon Sep 17 00:00:00 2001 From: tlylt Date: Fri, 18 Mar 2022 23:05:17 +0800 Subject: [PATCH 1/8] Update docs --- docs/userGuide/deployingTheSite.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/userGuide/deployingTheSite.md b/docs/userGuide/deployingTheSite.md index 29d041a0a9..3b49146e03 100644 --- a/docs/userGuide/deployingTheSite.md +++ b/docs/userGuide/deployingTheSite.md @@ -118,6 +118,28 @@ The sample `deploy.yml` workflow above uses the [default Github Token secret](ht Once you have created the file, commit and push the file to your repo. Github Actions should start to build and deploy your markbind site. You can verify this by visiting `www.github.com///actions`. + + +MarkBind provides a helper GitHub Action that you can use to simplify your workflow file. A sample workflow file utilizing the action is as follows: +```yml +name: Deploy MarkBind Site +on: + push: + branches: master + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + steps: + - name: Build & Deploy to GitHub Pages + uses: tlylt/markbind-deploy@main + with: + token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} + baseUrl: '/repoName' +``` +Read the [action documentation](https://github.com/tlylt/markbind-deploy/blob/main/README.md) to understand the various configuration options. + + For more information on customizing your workflow file to fit your specific needs, you may refer to the [Github Action Docs](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions). From bfaf823027c36b46cfae471bee2f717ae7bdc3ae Mon Sep 17 00:00:00 2001 From: tlylt Date: Tue, 29 Mar 2022 09:38:00 +0800 Subject: [PATCH 2/8] Update devdocs --- docs/_markbind/layouts/devGuide.md | 3 ++ docs/devGuide/githubActions/markbindAction.md | 33 +++++++++++++++++++ docs/devGuide/githubActions/overview.md | 22 +++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 docs/devGuide/githubActions/markbindAction.md create mode 100644 docs/devGuide/githubActions/overview.md diff --git a/docs/_markbind/layouts/devGuide.md b/docs/_markbind/layouts/devGuide.md index 6412945cdf..220d96194c 100644 --- a/docs/_markbind/layouts/devGuide.md +++ b/docs/_markbind/layouts/devGuide.md @@ -15,6 +15,9 @@ * [Architecture]({{baseUrl}}/devGuide/design/architecture.html) * [Server Side Rendering]({{baseUrl}}/devGuide/design/serverSideRendering.html) * [Writing Plugins]({{baseUrl}}/devGuide/writingPlugins.html) +* GitHub Actions :expanded: + * [Overview]({{baseUrl}}/devGuide/githubActions/overview.html) + * [markbind-action]({{baseUrl}}/devGuide/githubActions/markbindAction.html) * [Project management]({{baseUrl}}/devGuide/projectManagement.html) * Appendices :expanded: * [Style guides]({{baseUrl}}/devGuide/styleGuides.html) diff --git a/docs/devGuide/githubActions/markbindAction.md b/docs/devGuide/githubActions/markbindAction.md new file mode 100644 index 0000000000..b5484ce01a --- /dev/null +++ b/docs/devGuide/githubActions/markbindAction.md @@ -0,0 +1,33 @@ +{% set title = "GitHub Actions: markbind-action" %} +{{ title }} + + + title: "{{ title }}" + layout: devGuide.md + pageNav: default + + +# {{ title }} + +
+ +A GitHub Action that builds and deploys your MarkBind site. The source code is at [MarkBind/markbind-action](https://github.com/MarkBind/markbind-action). +
+ +**Follow these steps to get started on development** + +1. Fork the action repository and create a PR branch +2. Learn the workflow syntax in the repository's readme +3. Make necessary changes to the workflow files & update the readme +4. Set up a test repository that contains a markbind site + 1. Create a repository + 2. Set up MarkBind and run `markbind init` to populate with default content + 3. Push your repository to GitHub + 4. [Example](https://github.com/tlylt/mb-test) +5. Include a workflow file in the repository that uses your forked version of the action + 1. Instead of using `uses: MarkBind/markbind-action@v2` in the workflow file, use `uses: yourGitHubName/markbind-action@yourBranch` + 1. e.g. `uses: tlylt/markbind-action@master` + 2. [Example](https://github.com/tlylt/mb-test/tree/main/.github/workflows) +6. Trigger the action as required, check and validate the run result in action logs +7. Submit PRs + diff --git a/docs/devGuide/githubActions/overview.md b/docs/devGuide/githubActions/overview.md new file mode 100644 index 0000000000..b920277802 --- /dev/null +++ b/docs/devGuide/githubActions/overview.md @@ -0,0 +1,22 @@ +{% set title = "GitHub Actions: Overview" %} +{{ title }} + + + title: "{{ title }}" + layout: devGuide.md + pageNav: default + + +# {{ title }} + +
+ +A GitHub Action can perform a variety of tasks, including automating the build and deployment of your MarkBind site. +- [MarkBind/markbind-action](https://github.com/MarkBind/markbind-action) +
+ +**Before any development, ensure you have a basic knowledge of GitHub Actions** +* [Official GitHub Actions documentation](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) + * [Workflow syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) + * [Creating a composite action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) + * [Releasing and maintaining actions](https://docs.github.com/en/actions/creating-actions/releasing-and-maintaining-actions) From 362826227474ad732281bc50fd66368a4f3f6a61 Mon Sep 17 00:00:00 2001 From: tlylt Date: Tue, 29 Mar 2022 09:40:27 +0800 Subject: [PATCH 3/8] Update UG reference links --- docs/userGuide/deployingTheSite.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/userGuide/deployingTheSite.md b/docs/userGuide/deployingTheSite.md index 3b49146e03..e3be908132 100644 --- a/docs/userGuide/deployingTheSite.md +++ b/docs/userGuide/deployingTheSite.md @@ -131,13 +131,12 @@ jobs: build_and_deploy: runs-on: ubuntu-latest steps: - - name: Build & Deploy to GitHub Pages - uses: tlylt/markbind-deploy@main + - name: Build & Deploy MarkBind site + uses: MarkBind/markbind-action@v2 with: token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - baseUrl: '/repoName' ``` -Read the [action documentation](https://github.com/tlylt/markbind-deploy/blob/main/README.md) to understand the various configuration options. +Read the [action documentation](https://github.com/MarkBind/markbind-action#readme) to understand the various configuration options. For more information on customizing your workflow file to fit your specific needs, you may refer to the [Github Action Docs](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions). From c78c89870e74cf6e4f78fba451c240b8702bf568 Mon Sep 17 00:00:00 2001 From: Liu YongLiang <41845017+tlylt@users.noreply.github.com> Date: Fri, 1 Apr 2022 10:33:47 +0800 Subject: [PATCH 4/8] Update docs/devGuide/githubActions/markbindAction.md Co-authored-by: Jonah Tan <47470981+jonahtanjz@users.noreply.github.com> --- docs/devGuide/githubActions/markbindAction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devGuide/githubActions/markbindAction.md b/docs/devGuide/githubActions/markbindAction.md index b5484ce01a..a183affc66 100644 --- a/docs/devGuide/githubActions/markbindAction.md +++ b/docs/devGuide/githubActions/markbindAction.md @@ -19,7 +19,7 @@ A GitHub Action that builds and deploys your MarkBind site. The source code is a 1. Fork the action repository and create a PR branch 2. Learn the workflow syntax in the repository's readme 3. Make necessary changes to the workflow files & update the readme -4. Set up a test repository that contains a markbind site +4. Set up a test repository that contains a MarkBind site 1. Create a repository 2. Set up MarkBind and run `markbind init` to populate with default content 3. Push your repository to GitHub From d68cb371ce4e991f814a146679ef34e8fa49f6f4 Mon Sep 17 00:00:00 2001 From: Liu YongLiang Date: Fri, 1 Apr 2022 10:48:13 +0800 Subject: [PATCH 5/8] Update Dev docs --- docs/devGuide/githubActions/markbindAction.md | 31 ++++++++++--------- docs/devGuide/githubActions/overview.md | 2 +- 2 files changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/devGuide/githubActions/markbindAction.md b/docs/devGuide/githubActions/markbindAction.md index a183affc66..589e236243 100644 --- a/docs/devGuide/githubActions/markbindAction.md +++ b/docs/devGuide/githubActions/markbindAction.md @@ -11,23 +11,26 @@
-A GitHub Action that builds and deploys your MarkBind site. The source code is at [MarkBind/markbind-action](https://github.com/MarkBind/markbind-action). +A GitHub Action that builds and deploys your MarkBind site. It helps users to streamline their workflow by: +* Making it easier to deploy without having to write their own actions from scratch +* Making the workflows consistent and up to date with any changes specific to MarkBind + +The source code is at [MarkBind/markbind-action](https://github.com/MarkBind/markbind-action).
**Follow these steps to get started on development** 1. Fork the action repository and create a PR branch -2. Learn the workflow syntax in the repository's readme -3. Make necessary changes to the workflow files & update the readme -4. Set up a test repository that contains a MarkBind site +1. Learn the workflow syntax in the repository's readme +1. Make necessary changes to the workflow files & update the readme +1. Set up a test repository that contains a MarkBind site 1. Create a repository - 2. Set up MarkBind and run `markbind init` to populate with default content - 3. Push your repository to GitHub - 4. [Example](https://github.com/tlylt/mb-test) -5. Include a workflow file in the repository that uses your forked version of the action - 1. Instead of using `uses: MarkBind/markbind-action@v2` in the workflow file, use `uses: yourGitHubName/markbind-action@yourBranch` - 1. e.g. `uses: tlylt/markbind-action@master` - 2. [Example](https://github.com/tlylt/mb-test/tree/main/.github/workflows) -6. Trigger the action as required, check and validate the run result in action logs -7. Submit PRs - + 1. Set up MarkBind and run `markbind init` to populate with default content + 1. Push your repository to GitHub + * [Example](https://github.com/MarkBind/init-typical) +1. Include a workflow file in the repository that uses your forked version of the action + * Instead of using `uses: MarkBind/markbind-action@v2` in the workflow file, use `uses: yourGitHubName/markbind-action@yourBranch` + * e.g. `uses: tlylt/markbind-action@master` + * [Example](https://github.com/tlylt/mb-test/tree/main/.github/workflows) +1. Trigger the action as required, check and validate the run result in action logs +1. Submit PRs \ No newline at end of file diff --git a/docs/devGuide/githubActions/overview.md b/docs/devGuide/githubActions/overview.md index b920277802..5946f80406 100644 --- a/docs/devGuide/githubActions/overview.md +++ b/docs/devGuide/githubActions/overview.md @@ -12,7 +12,7 @@
A GitHub Action can perform a variety of tasks, including automating the build and deployment of your MarkBind site. -- [MarkBind/markbind-action](https://github.com/MarkBind/markbind-action) +* [MarkBind/markbind-action](https://github.com/MarkBind/markbind-action) is a [published action](https://github.com/marketplace/actions/markbind-action) that builds and deploys your MarkBind site.
**Before any development, ensure you have a basic knowledge of GitHub Actions** From 4cce83a753310dccf1e35f54bb64a378648dcb0e Mon Sep 17 00:00:00 2001 From: Liu YongLiang <41845017+tlylt@users.noreply.github.com> Date: Fri, 1 Apr 2022 16:18:40 +0800 Subject: [PATCH 6/8] Update docs/devGuide/githubActions/markbindAction.md Co-authored-by: Hannah <59471320+kaixin-hc@users.noreply.github.com> --- docs/devGuide/githubActions/markbindAction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devGuide/githubActions/markbindAction.md b/docs/devGuide/githubActions/markbindAction.md index 589e236243..b36c8794bb 100644 --- a/docs/devGuide/githubActions/markbindAction.md +++ b/docs/devGuide/githubActions/markbindAction.md @@ -11,7 +11,7 @@
-A GitHub Action that builds and deploys your MarkBind site. It helps users to streamline their workflow by: +A GitHub Action that builds and deploys a MarkBind site. It helps users to streamline their workflow by: * Making it easier to deploy without having to write their own actions from scratch * Making the workflows consistent and up to date with any changes specific to MarkBind From 9ae7e4cc51ac526ad4ebb79348aaf1ae0321c0c6 Mon Sep 17 00:00:00 2001 From: tlylt Date: Fri, 1 Apr 2022 23:34:32 +0800 Subject: [PATCH 7/8] Update docs --- docs/devGuide/githubActions/markbindAction.md | 42 ++++++++++++++----- docs/devGuide/githubActions/overview.md | 2 +- 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/docs/devGuide/githubActions/markbindAction.md b/docs/devGuide/githubActions/markbindAction.md index b36c8794bb..d8bd30b1e0 100644 --- a/docs/devGuide/githubActions/markbindAction.md +++ b/docs/devGuide/githubActions/markbindAction.md @@ -18,19 +18,39 @@ A GitHub Action that builds and deploys a MarkBind site. It helps users to strea The source code is at [MarkBind/markbind-action](https://github.com/MarkBind/markbind-action).
-**Follow these steps to get started on development** - -1. Fork the action repository and create a PR branch -1. Learn the workflow syntax in the repository's readme -1. Make necessary changes to the workflow files & update the readme -1. Set up a test repository that contains a MarkBind site +**Follow these steps to get started on modifying the source code** +## Setting Up +1. Fork the [action repository](https://github.com/MarkBind/markbind-action) +1. Learn the existing workflow syntax/options provided in the repository's [readme.md](https://github.com/MarkBind/markbind-action#readme) +1. Set up a repository that contains a MarkBind site to test the action as a user 1. Create a repository 1. Set up MarkBind and run `markbind init` to populate with default content 1. Push your repository to GitHub * [Example](https://github.com/MarkBind/init-typical) -1. Include a workflow file in the repository that uses your forked version of the action - * Instead of using `uses: MarkBind/markbind-action@v2` in the workflow file, use `uses: yourGitHubName/markbind-action@yourBranch` - * e.g. `uses: tlylt/markbind-action@master` + +## Modifying the action +1. Create a new branch from master to work on your changes +1. Make necessary modifications to the workflow files +1. Update the repository's readme.md to reflect the changes + +## Testing the action +1. Include a workflow file in your test repository to test your modified version of the action + * Instead of using `uses: MarkBind/markbind-action@v2` in the workflow file, use `uses: yourGitHubName/markbind-action@yourBranch` to reference the unpublished version of the action that you are currently developing + * e.g. `uses: tlylt/markbind-action@main` * [Example](https://github.com/tlylt/mb-test/tree/main/.github/workflows) -1. Trigger the action as required, check and validate the run result in action logs -1. Submit PRs \ No newline at end of file +1. Trigger the action as needed, check and validate the run result in the action logs + +You can now submit PRs to improve MarkBind's Github actions! 🎉 + +## Release Management +Based on the [Github Actions documentation](https://docs.github.com/en/actions/creating-actions/about-custom-actions#using-release-management-for-actions), we are using tags for release management. + + + +* Create and validate a release on a release branch (such as `release/v1`) before creating the release tag (for example, `v1.0.2`). +* Create a release using semantic versioning. For more information, see "[Creating releases](https://docs.github.com/en/articles/creating-releases)." +* Move the major version tag (such as `v1`, `v2`) to point to the Git ref of the current release. For more information, see "[Git basics - tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)." +* Introduce a new major version tag (`v2`) for changes that will break existing workflows. For example, changing an action's inputs would be a breaking change. + +(Taken from GitHub Actions documentation) + \ No newline at end of file diff --git a/docs/devGuide/githubActions/overview.md b/docs/devGuide/githubActions/overview.md index 5946f80406..03a2a11639 100644 --- a/docs/devGuide/githubActions/overview.md +++ b/docs/devGuide/githubActions/overview.md @@ -11,7 +11,7 @@
-A GitHub Action can perform a variety of tasks, including automating the build and deployment of your MarkBind site. +A GitHub Action can perform a variety of tasks, including automating the build and deployment of a MarkBind site. * [MarkBind/markbind-action](https://github.com/MarkBind/markbind-action) is a [published action](https://github.com/marketplace/actions/markbind-action) that builds and deploys your MarkBind site.
From 30c20af6de86a7be6ebc6347aefecef390656a7c Mon Sep 17 00:00:00 2001 From: tlylt Date: Sat, 2 Apr 2022 20:30:22 +0800 Subject: [PATCH 8/8] Update docs --- docs/devGuide/githubActions/markbindAction.md | 44 ++++++++----------- 1 file changed, 19 insertions(+), 25 deletions(-) diff --git a/docs/devGuide/githubActions/markbindAction.md b/docs/devGuide/githubActions/markbindAction.md index d8bd30b1e0..f790148d55 100644 --- a/docs/devGuide/githubActions/markbindAction.md +++ b/docs/devGuide/githubActions/markbindAction.md @@ -12,45 +12,39 @@
A GitHub Action that builds and deploys a MarkBind site. It helps users to streamline their workflow by: -* Making it easier to deploy without having to write their own actions from scratch -* Making the workflows consistent and up to date with any changes specific to MarkBind +* Making it easier to deploy without having to write their own actions from scratch. +* Making the workflows consistent and up to date with any changes specific to MarkBind. The source code is at [MarkBind/markbind-action](https://github.com/MarkBind/markbind-action).
-**Follow these steps to get started on modifying the source code** +**Follow the steps below to get started on modifying the source code.** ## Setting Up -1. Fork the [action repository](https://github.com/MarkBind/markbind-action) -1. Learn the existing workflow syntax/options provided in the repository's [readme.md](https://github.com/MarkBind/markbind-action#readme) -1. Set up a repository that contains a MarkBind site to test the action as a user - 1. Create a repository - 1. Set up MarkBind and run `markbind init` to populate with default content - 1. Push your repository to GitHub +1. Fork the [action repository](https://github.com/MarkBind/markbind-action). +1. Familiarise with the existing workflow syntax/options provided in the repository's [README.md](https://github.com/MarkBind/markbind-action#readme). +1. Set up a repository that contains a MarkBind site to test the action: + 1. Create a repository. + 1. Set up MarkBind and run `markbind init` to populate with default content. + 1. Push your repository to GitHub. * [Example](https://github.com/MarkBind/init-typical) ## Modifying the action -1. Create a new branch from master to work on your changes -1. Make necessary modifications to the workflow files -1. Update the repository's readme.md to reflect the changes +1. Create a new branch from master to work on your changes. +1. Make necessary modifications to the workflow files. +1. Update the repository's README.md to reflect the changes. ## Testing the action -1. Include a workflow file in your test repository to test your modified version of the action - * Instead of using `uses: MarkBind/markbind-action@v2` in the workflow file, use `uses: yourGitHubName/markbind-action@yourBranch` to reference the unpublished version of the action that you are currently developing +1. Include a workflow file in your test repository to test your modified version of the action. + * Instead of using `uses: MarkBind/markbind-action@v2` in the workflow file, use `uses: yourGitHubName/markbind-action@yourBranch` to reference the unpublished version of the action that you are currently developing. * e.g. `uses: tlylt/markbind-action@main` - * [Example](https://github.com/tlylt/mb-test/tree/main/.github/workflows) -1. Trigger the action as needed, check and validate the run result in the action logs +1. Trigger the action as needed, check and validate the results in the action logs. You can now submit PRs to improve MarkBind's Github actions! 🎉 ## Release Management Based on the [Github Actions documentation](https://docs.github.com/en/actions/creating-actions/about-custom-actions#using-release-management-for-actions), we are using tags for release management. - - -* Create and validate a release on a release branch (such as `release/v1`) before creating the release tag (for example, `v1.0.2`). -* Create a release using semantic versioning. For more information, see "[Creating releases](https://docs.github.com/en/articles/creating-releases)." -* Move the major version tag (such as `v1`, `v2`) to point to the Git ref of the current release. For more information, see "[Git basics - tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)." -* Introduce a new major version tag (`v2`) for changes that will break existing workflows. For example, changing an action's inputs would be a breaking change. - -(Taken from GitHub Actions documentation) - \ No newline at end of file +> * Create and validate a release on a release branch (such as `release/v1`) before creating the release tag (for example, `v1.0.2`). +> * Create a release using semantic versioning. For more information, see "[Creating releases](https://docs.github.com/en/articles/creating-releases)." +> * Move the major version tag (such as `v1`, `v2`) to point to the Git ref of the current release. For more information, see "[Git basics - tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)." +> * Introduce a new major version tag (`v2`) for changes that will break existing workflows. For example, changing an action's inputs would be a breaking change. \ No newline at end of file