mirror of https://github.com/actions/toolkit
versioning update (#246)
Bryan MacFarlane
GitHub
parent
5fdab2aaf2
commit
0f1fef3752
|
|
@ -17,7 +17,7 @@ Binding to a major version is the latest of that major version ( e.g. `v1` == "1
|
|||
|
||||
Major versions should guarantee compatibility. A major version can add net new capabilities but should not break existing input compatibility or break existing workflows.
|
||||
|
||||
Major version binding allows you to take advantage of bug fixes and critical functionality and security fixes. The `master` branch has the latest code and is unstable to bind to since a breaking new major version may first get implemented in master.
|
||||
Major version binding allows you to take advantage of bug fixes and critical functionality and security fixes. The `master` branch has the latest code and is unstable to bind to since changes get committed to master and released to the market place by creating a tag. In addition, a new major version carrying breaking changes will get implemented in master after branching off the previous major version.
|
||||
|
||||
> Warning: do not reference `master` since that is the latest code and can be carrying breaking changes of the next major version.
|
||||
|
||||
|
|
@ -32,30 +32,18 @@ Binding to the immutable sha1 may offer more reliability. However, note that th
|
|||
|
||||
# Recommendations
|
||||
|
||||
1. **Create a release branch for each major version**: For example, `releases/v1`. This will allow for releases of that major version while the development of a different major version proceeds.
|
||||
1. **Create a GitHub release for each specific version**: Creating a release like [ v1.0.0 ](https://github.com/actions/javascript-action/releases/tag/v1.0.0) allows users to bind back to a specific version if an issue is encountered with the latest major version.
|
||||
|
||||
2. **Validate changes referencing the release branch**:
|
||||
2. **Publish the specific version to the marketplace**: When you release a specific version, choose the option to "Publish this release to the GitHub Marketplace".
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- uses: actions/sample-action@releases/v1
|
||||
```
|
||||
|
||||
3. **Create a GitHub release for each specific version**: Creating a release like [ v1.0.0 ](https://github.com/actions/javascript-action/releases/tag/v1.0.0) allows users to bind back to a specific version if an issue is encountered with the latest major version.
|
||||
|
||||
4. **Release that version by updating the major version tag**: Move the major version tag (v1, v2, etc.) to point to the ref of the current release. This will act as the stable release for that major version. You should keep this tag updated to the most recent stable minor/patch release.
|
||||
3. **Make the new release available to those binding to the major version tag**: Move the major version tag (v1, v2, etc.) to point to the ref of the current release. This will act as the stable release for that major version. You should keep this tag updated to the most recent stable minor/patch release.
|
||||
|
||||
```
|
||||
git checkout releases/v1
|
||||
git tag -fa v1 -m "Update v1 tag"
|
||||
git push origin v1 --force
|
||||
```
|
||||
|
||||
This will result in a major version tag and the latest specific version pointing to the same SHA. See [javascript-action tags](https://github.com/actions/javascript-action/tags) as an example.
|
||||
|
||||
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)
|
||||
4. **Create a new major version if breaking compat**: If the inputs or behavior are breaking, offer a new major version. Typically, this entails branching the previous major version for critical updates and moving master to the new major version. Keeping the major versions available to a minimum is desirable as adding new major versions requires end users understanding the breaks (how to adjust their yaml and expectations). Since you will likely want to innovate on just the latest major version with only critical updates to previous major versions, you will want to encourage users to move to the latest major version. For that reason, it's best to combine breaking changes with new capabilities.
|
||||
|
||||
# Sample Workflow
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
<mxfile modified="2019-09-04T11:27:58.307Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36" etag="MFzGVuAX-y50cwbudjLg" version="11.2.5" type="device" pages="1"><diagram name="Page-1" id="ff44883e-f642-bcb2-894b-16b3d25a3f0b">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==</diagram></mxfile>
|
||||
<mxfile modified="2019-12-07T22:13:10.645Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.108 Safari/537.36" etag="uH_pE3PCpuTQ4qsuLdZa" version="12.3.8" type="device" pages="1"><diagram name="Page-1" id="ff44883e-f642-bcb2-894b-16b3d25a3f0b">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</diagram></mxfile>
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 62 KiB After Width: | Height: | Size: 66 KiB |
Loading…
Reference in New Issue