From edf75b79beeaba2a705bf36aa19a4daad17da486 Mon Sep 17 00:00:00 2001 From: Adam Hernandez Date: Mon, 5 Feb 2024 14:40:41 -0700 Subject: [PATCH] update readme --- README.md | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- action.yml | 8 ++--- 2 files changed, 98 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d17f4cc..280443c 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,94 @@ -# action-workflow-documenter -project that will document workflows and output it to the repository wiki +# Action Workflow Documenter +This tool will document action workflows in a repository + +## Index + +- [Inputs](#inputs) +- [Outputs](#outputs) +- [Example](#example) +- [Contributing](#contributing) + - [Incrementing the Version](#incrementing-the-version) + - [Source Code Changes](#source-code-changes) + - [Updating the README.md](#updating-the-readmemd) +- [Code of Conduct](#code-of-conduct) +- [License](#license) + +## Inputs + +| Parameter | Is Required | Default Value | Description | +| ------------------ | ----------- | --------------- | ------------------------------------------------------------------ | +| `github-pat` | true | None | The github personal access token used for interactions with github. | +| `save-to-artifact` | false | None | If `true`, save to documentation as an artifact. Used for testing. | +| `save-to-branch` | false | None | If `true`, save to documentation to a branch | +| `save-to-wiki` | false | None | If `true`, save to documentation to repository's wiki | + + +## Outputs + +This workflow has zero outputs. + +## Example + +```yml +jobs: + job1: + runs-on: [self-hosted, im-linux] + steps: + ... + - name: 'Document Workflows' + uses: ahernandez411/action-workflow-documenter@v1.0.1 + with: + github-pat: ${{ secrets.GITHUB_TOKEN }} + save-to-artifact: 'false' + save-to-branch: 'false' + save-to-wiki: 'false' + ... +``` + +## Contributing + +When creating PRs, please review the following guidelines: + +- [ ] The action code does not contain sensitive information. +- [ ] At least one of the commit messages contains the appropriate `+semver:` keywords listed under [Incrementing the Version] for major and minor increments. +- [ ] The README.md has been updated with the latest version of the action. See [Updating the README.md] for details. + +### Incrementing the Version + +This repo uses [git-version-lite] in its workflows to examine commit messages to determine whether to perform a major, minor or patch increment on merge if [source code] changes have been made. The following table provides the fragment that should be included in a commit message to active different increment strategies. + +| Increment Type | Commit Message Fragment | +|----------------|---------------------------------------------| +| major | +semver:breaking | +| major | +semver:major | +| minor | +semver:feature | +| minor | +semver:minor | +| patch | *default increment type, no comment needed* | + +### Source Code Changes + +The files and directories that are considered source code are listed in the `files-with-code` and `dirs-with-code` arguments in both the [build-and-review-pr] and [increment-version-on-merge] workflows. + +If a PR contains source code changes, the README.md should be updated with the latest action version. The [build-and-review-pr] workflow will ensure these steps are performed when they are required. The workflow will provide instructions for completing these steps if the PR Author does not initially complete them. + +If a PR consists solely of non-source code changes like changes to the `README.md` or workflows under `./.github/workflows`, version updates do not need to be performed. + +### Updating the README.md + +If changes are made to the action's [source code], the [usage examples] section of this file should be updated with the next version of the action. Each instance of this action should be updated. This helps users know what the latest tag is without having to navigate to the Tags page of the repository. See [Incrementing the Version] for details on how to determine what the next version will be or consult the first workflow run for the PR which will also calculate the next version. + +## Code of Conduct + +This project has adopted the [im-open's Code of Conduct](https://github.com/im-open/.github/blob/main/CODE_OF_CONDUCT.md). + +## License + +Copyright © 2023, Extend Health, LLC. Code released under the [MIT license](LICENSE). + +[git-version-lite]: https://github.com/im-open/git-version-lite +[Incrementing the Version]: #incrementing-the-version +[Updating the README.md]: #updating-the-readmemd +[build-and-review-pr]: ./.github/workflows/build-and-review-pr.yml +[increment-version-on-merge]: ./.github/workflows/increment-version-on-merge.yml +[source code]: #source-code-changes +[usage examples]: #usage-examples diff --git a/action.yml b/action.yml index 2d4c962..ecbb1e5 100644 --- a/action.yml +++ b/action.yml @@ -7,14 +7,14 @@ inputs: description: The github personal access token used for interactions with github. required: true save-to-artifact: - description: If true, save to documentation as an artifact - required: true + description: If true, save to documentation as an artifact. This is mostly used for testing purposes. + required: false save-to-branch: description: If true, save to documentation to a branch - required: true + required: false save-to-wiki: description: If true, save to documentation to repository's wiki - required: true + required: false permissions: contents: write