diff --git a/README.md b/README.md index 14fdc71c..b5a2d40d 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,9 @@ The toolkit provides five separate packages. See the docs for each action. Actions are units of work which can either run in a container or on the host machine. -[Choosing an action type](docs/action-types.md): Outlines the differences and why you would want to create a host or a container based action. +[Choosing an action type](docs/action-types.md): Outlines the differences and why you would want to create a JavaScript or a container based action. -[JavaScript Action Walkthrough](docs/javascript-action.md): A full walkthrough creating an action using the toolkit along with TypeScript and Jest for unit testing. It also covers a branching strategy for versioning and safely testing and releasing an action. +[JavaScript Action Walkthrough using a Template](docs/javascript-action.md): A full walkthrough creating an action using the toolkit along with TypeScript for compile time support and Jest for unit testing. It also covers a branching strategy for versioning and safely testing and releasing an action. [Docker Action Walkthrough](docs/container-action.md): Create an action that is delivered as a container and run with docker. diff --git a/docs/action-versioning.md b/docs/action-versioning.md index a8f7e7e8..4e8a6c65 100644 --- a/docs/action-versioning.md +++ b/docs/action-versioning.md @@ -41,3 +41,9 @@ git push origin v1 5. **Compatibility Breaks**: introduce a new major version branch (releases/v2) and tag (v2) if changes will break existing workflows. For example, changing inputs. See [Git-Basics-Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) + +# Sample Workflow + +This illustrates one possible versioning workflow which the walk through covered. + +![versioning](assets/action-releases.png) diff --git a/docs/assets/action-releases.drawio b/docs/assets/action-releases.drawio new file mode 100644 index 00000000..b5a00666 --- /dev/null +++ b/docs/assets/action-releases.drawio @@ -0,0 +1 @@ +7Vtbc5s4GP01nj4lA+L+WCdp96E70910uu1TB4OMmWDkEdhx9tfvJ5AMSPIta4Mbx5mJ0R10zncVHll38/VnGi5mf5IYZyNkxOuRdT9CyHds+M8qXuoKxzPqioSmcV1lNhWP6b+YV4puyzTGRadjSUhWpotuZUTyHEdlpy6klDx3u01J1l11ESZYqXiMwkzU3jpN/T9pXM54vekGTcMfOE1mfHEfuXXDJIyeEkqWOV9xhKxp9amb56GYiz9qMQtj8tyqsh5G1h0lpKyv5us7nLHNFRsnxpUv4m5H1nhWzjMomHBZNX/aMtg8ZDA8HMV52V5u23xTYxJFQWAZNnanTngTKPPjGHaWF3OSw9c4WtIVjvmKrcWLMqQlJwMwwRrjPP7I0IRylIVFkUZ15ac0E2Og1B5RlJQ84TuSEVotbxnVZ9MisGSPPSX5ZjVUTVXSlx+beaHwEwoGUIEX7xm9jU3pRZTWafmjdd0aBaVmECuIMeo+C2TIkkZYv7mIS0JIE1zqu/BZ2Ka3puXYfcZkjuHOoQPFWVimq64QhFxqkk2/zdCvJIUbRQYXcFsIKpdvT8i3mKJ+DD6q4Q9ctG6jqapYdRjDTPfUFNvHpp2c0WG/E/kNy1rE+tkm3RaWvYox1n7GoH4YY0mM8WXG1Pd4FsbUC63CbMnvPlLVIEwBxoVR53mWlvhxEVZ7+gzmrcugSrVX1KoYIrS3qVM+bvVRiGR3iWSxicIsTXKm5wBeTFkHYGVrqqnD/nbxYIVpidc7MeStyO9isbHOz42lE11mbRtnbEe9g9cx4Kjm7NLEeY8qf63ZeJVAuxcj0E4gkcjqTaCRKtBoUIE2BxZo27scgbZUcKyrBseRwPHRcODYKjjOVYPjyVpsSFNov5vCI0yhvd8Uuv2YQs8azBS6qkBrWHRFAu3awwl08ovef//7r+Rhtfj+7UtBvkR3N5roY4TcDFYdT+AiqS5omEdwbx9FCyy0aYTvcM5wyicF+wKu4rDABfRZqWEMYLZgl1GYZWRZ7od8gWkKD8pgEYO+NlXjBSnSMiU5quTY9E9kEiWt69kqSCbqEyWNSznD0VOas0elJGa5TLwAJYrzKGWbzyGkAqZvuGAa4QE9KJjAppSyrm4LE1fsbaHgVYrgsC1OAaaPvGGexnG2TbC70nwK2XKdrifja2DTCRc6F2waZ1OTHroi9ee7wzmbWoTefZpdPs0uUu9ybKx+HBsnMG890/GQ7zng1XhBl1u2tnVPClhdBHUp67pn85602+0oOmSartmgolgyTW9MKZkzPEDDp3nydtW7Z3TVu2vZqno3+lTvl5nq3yiMgZP9r1Uedj/Kw5fzHgeeESkTubJNO9/RgXZLPUVBzDEsCFUgzGybJuCPv1214DuSftZEVHafWsFX8FAiqojisMQ1h3GFDtzMuJKLZGucZZi3EOKorr0y+85Jeg/KwO6eRv17clBmqurf7dN3DPYDfVToPA8LtoG/Z8yMpJjZDoaOmcXRXTv68lSLfUXRV3BxySfNQfcFeFBHhF+v94QEPc/u5xiSfZQN36F+juwwuWa/fo6pSYL51y3Pgd/1PIfOppiao9TfS577T6cIWrdDol2h03tcdCgZLzO3d2uDlDSEvDFujQMpeWSQziZp+X190bQvuxbIb+zJp5oH2zXJK+o7wWeqGb6rCuBNQ/ZQPEsxY71G8KZ6bF3nXCfLN5xf9QPZUVTzq/3CoGa2ytYxJgjGFFN24Mmy3oZ08Gzw0BsZH0DNwLAPcLnMea/47cIY2N1jkMBAA8N41oQYOiAhNicrvG+u3vNilv73LMfj7Xfx1r6s0GtezFQTY1tSW5chdJWrxm9KCunYxp/Exsnv8QWBApIOo7MJpZi4hdHuN3euByp/i1+5L5F5Pqx072jJkU3zUzS+7XFYzHSBzcFbtteBb22Io9kPUfc//XwZD09OOx3q55umfIJwsgQWFJtfRNbdm9+dWg//AQ== \ No newline at end of file diff --git a/docs/assets/action-releases.png b/docs/assets/action-releases.png new file mode 100644 index 00000000..9cf7e80b Binary files /dev/null and b/docs/assets/action-releases.png differ diff --git a/docs/javascript-action.md b/docs/javascript-action.md index 55a3f55a..2e31cedf 100644 --- a/docs/javascript-action.md +++ b/docs/javascript-action.md @@ -6,32 +6,30 @@ The [javascript-template](https://github.com/actions/javascript-template) repo c Navigate to https://github.com/actions/javascript-template -Click on `Use this template` to create the repo for your action. +Click on `Use this template` to create the repo for your action. Provide a name such as `myaction` (used in rest of walk through). ![template](assets/node12-template.png) -Complete creating your repo and clone the repo. +# Clone and Update -> NOTE: The location of the repo will be how users will reference your action in their workflow file with the using keyword. - -e.g. To use https://github.com/actions/setup-node, user's will author: - -```yaml -steps: - uses: actions/setup-node@master +```bash +$ git clone +$ cd myaction ``` +Update the `author` element in the package.json file. + # Dev Workflow The workflow below describes one possible workflow with a branching strategy. Others exist. -> Key Point: the branch that users reference in their workflow files should reference an action that has **only** the production dependencies. +> Key Point: the branch that users reference in their workflow files should reference an action from a distribution branch that **only** has the production dependencies. -The workflow below describes a strategy where you code in master (with node_modules ignored) with a v1 branch users reference and contains the product references. Actions are self contained referenced on the github graph of repos. +The workflow below describes a strategy where you code in master (with node_modules ignored) with a distribution releases/v1 branch users reference via a tag. Actions are self contained referenced from the github graph of repos, downloaded by the runner and run intact at runtime. ## Install Dependencies -After creating a repo from the template and cloning it, you will be in master. The command below will install the toolkit, other dependencies and dev dependencies +After creating a repo from the template and cloning it, you will be in master. The command below will install the toolkit, other dependencies and dev dependencies. node_modules are ignored in the coding master branch. ```bash $ npm install @@ -39,24 +37,24 @@ $ npm install ## Define Metadata -Your action has a name and a description. Update the author. - -Create inputs that your unit of work will need. These will be what workflow authors set with the `with:` keyword. +Your action has a name and a description. Update all fields . ```yaml -name: 'My new action' -description: 'A test action' -author: 'GitHub' +name: 'Hello' +description: 'Outputs Hello to a named input' +author: 'me' inputs: - myInput: - description: 'Input to use' - default: 'world' + name: + description: 'the name to say hello to' + default: 'World' runs: using: 'node12' main: 'lib/main.js' ``` +The `name` input will be referenced by workflow authors using the `with:` keyword. + Note that the action will be run with node 12 (carried by the runner) and the entry point is specified with `main:` ## Change Code and Add Tests @@ -68,8 +66,8 @@ import * as core from '@actions/core'; async function run() { try { - const myInput = core.getInput('myInput'); - core.debug(`Hello ${myInput}!`); + const nameInput = core.getInput('name'); + console.log(`Hello ${nameInput}!`); } catch (error) { core.setFailed(error.message); } @@ -78,14 +76,14 @@ async function run() { run(); ``` -Modify tests in `__tests__/main.test.ts`. The template uses [jest](https://github.com/facebook/jest). +Note that tests are in `__tests__/main.test.ts`. The template uses [jest](https://github.com/facebook/jest) to get you started with unit testing. ## Build and Test ```bash $ npm run build -> node12-template-action@0.0.0 build /Users/user/Projects/testnode12 +> javascript-template-action@0.0.0 build /Users/user/Projects/myaction > tsc $ npm test @@ -107,12 +105,12 @@ $ git add $ git commit -m "Message" ``` -## Publish a v1-release Action +## Publish a releases/v1 Action -After changing some files, create a v1-release branch which we will release +After changing some files, create a releases/v1 branch which we will release ```bash -$ git checkout -b v1-release +$ git checkout -b releases/v1 ``` > NOTE: We will provide tooling and an action to automate this soon. @@ -139,7 +137,9 @@ Once the action has a self contained version in the v1-release branch, you can t ```yaml steps: - uses: {org}/{reponame}@v1-release + uses: myorg/myaction@releases/v1 + with: + name: World! ``` ## Release Current Changes as v1 @@ -154,7 +154,9 @@ Users can now reference your action in their workflows with ```yaml steps: - uses: {org}/{reponame}@v1 + uses: myorg/myaction@v1 + with: + name: World! ```