diff --git a/.gitattributes b/.gitattributes index 3fdfd82c1..a9c4f17c8 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,5 +1,11 @@ -# Set the default behavior, in case people don't have core.autocrlf set. * text=auto -# Denote all files that are truly binary and should not be modified. +*.json text eol=lf *.png binary + +src/step-templates/*/scriptbody.ps1 -text +src/step-templates/*/predeploy.ps1 -text +src/step-templates/*/deploy.ps1 -text +src/step-templates/*/postdeploy.ps1 -text +src/step-templates/*/scriptbody.sh -text +src/step-templates/*/scriptbody.py -text diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 546784b13..6af02b7b8 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -6,22 +6,19 @@ Have a great custom step that other Octopus users will love? Here's how to get i 1. [Fork](https://github.com/OctopusDeploy/Library/fork) the Library repository 2. Clone your fork into a directory on your own machine 3. _Export_ your template from the Octopus server -4. Save the exported JSON to a file under `/step-templates` -5. Check that the `LastModifiedBy` username is one you're happy to use on the site (ideally your plain GitHub username) -6. Add Id property and set it to a GUID using the following format `abcdef00-ab00-cd00-ef00-000000abcdef`, you can use [this site](https://www.guidgen.com/) to generate one automatically -7. Optional: Assign your template to an existing category. Have a look at existing templates to find the category that matches your template. If you don't specify it your template will be assigned to 'other' category. - - If you add a new category, make sure that you add an icon in `.png` format with a size of 200x200px to the `logos` folder with the same name as your category. Also, the `switch` in the `humanize` function in [`gulpfile.babel.js`](https://github.com/OctopusDeploy/Library/blob/master/gulpfile.babel.js#L92) must have a `case` statement corresponding to it. -8. If you're updating an existing step template, make sure the `Version` property is incremented (e.g. by 1). If the `Version` doesn't change then the [Community Library Integration](http://docs.octopusdeploy.com/display/OD/Step+Templates#StepTemplates-TheCommunityLibrary) in Octopus won't see your changes. -9. Commit and push your changes to your fork -10. View your fork in GitHub to create a _pull request_ +4. If you are starting from an exported JSON file, save it under `/step-templates`, run `powershell .\tools\_unpack.ps1 -SearchPattern "template-name"`, then move the resulting files into `/src/step-templates//` +5. Author step templates in `/src/step-templates//`, with `metadata.json` beside `scriptbody.ps1`, `scriptbody.sh`, or `scriptbody.py` as needed +6. Check that the `LastModifiedBy` username is one you're happy to use on the site (ideally your plain GitHub username) +7. Add Id property and set it to a GUID using the following format `abcdef00-ab00-cd00-ef00-000000abcdef`, you can use [this site](https://www.guidgen.com/) to generate one automatically +8. Optional: Assign your template to an existing category. Have a look at existing templates to find the category that matches your template. If you don't specify it your template will be assigned to 'other' category. + - If you add a new category, make sure that you add an icon in `.png` format with a size of 200x200px to the `src/step-templates/logos` folder with the same name as your category. Also, the `switch` in the `humanize` function in [`gulpfile.babel.js`](https://github.com/OctopusDeploy/Library/blob/master/gulpfile.babel.js#L92) must have a `case` statement corresponding to it. +9. If you're updating an existing step template, make sure the `Version` property is incremented (e.g. by 1). If the `Version` doesn't change then the [Community Library Integration](http://docs.octopusdeploy.com/display/OD/Step+Templates#StepTemplates-TheCommunityLibrary) in Octopus won't see your changes. +10. Commit and push your changes to your fork +11. View your fork in GitHub to create a _pull request_ Someone from the Octopus team will review your request and help to make the step consistent with the others in the library. Once it's ready we'll merge it into the main repository and publish it to [the library site](http://library.octopusdeploy.com). -**Note**: If you're editing an existing template we've got a tool you can use to help with packing and unpacking the scripts stored in the step template `*.json` file. - -* To unpack the step template scripts into separate files alongside the main step template file, run `powershell .\tools\_unpack.ps1`. -* You can then edit the `*.ps1` files in the `.\step-templates` folder using your favourite PowerShell editor. -* To pack the step template script files back into the main step template, run `powershell .\tools\_pack.ps1`. +**Note**: This repository now treats `src/step-templates/**` as the source of truth. Build tooling must continue to generate `step-templates/*.json`, and that generated JSON is the compatibility output this repository is preserving. The exact retrieval flow used by `library.octopus.com` is not documented here, but generated JSON in the legacy location is believed to remain compatible. Here's a **checklist** to consider: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9f007c1d4..a0b0d6f3c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -41,7 +41,7 @@ _Before submitting your PR, please delete everything above the line below._ - [ ] `LastModifiedBy` field must be present, and (_optionally_) updated with the correct author - [ ] The best practices documented [here](https://github.com/OctopusDeploy/Library/wiki/Best-Practices) have been applied - [ ] If a new `Category` has been created: - - [ ] An image with the name `{categoryname}.png` must be present under the `step-templates/logos` folder + - [ ] An image with the name `{categoryname}.png` must be present under the `src/step-templates/logos` folder - [ ] The `switch` in the `humanize` function in [`gulpfile.babel.js`](https://github.com/OctopusDeploy/Library/blob/master/gulpfile.babel.js#L92) must have a `case` statement corresponding to it Fixes # . _If there is an open issue that this PR fixes add it here, otherwise just remove this line_ diff --git a/.gitignore b/.gitignore index 96cc31e06..0e2737b80 100644 --- a/.gitignore +++ b/.gitignore @@ -9,9 +9,8 @@ junitresults.xml scriptcs_packages/ scriptcs_packages.config -step-templates/*.ps1 -step-templates/*.sh -step-templates/*.py +/step-templates/ +/step-templates-orig/ diff-output/ /.vs !.vscode diff --git a/README.md b/README.md index 427d328aa..ca078f7c1 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A repository of step templates and other community-contributed extensions to Oct Organization ------------ -* *Step templates* are checked into `/step-templates` as raw JSON exports direct from Octopus Deploy +* *Step templates* are authored under `/src/step-templates`, with generated compatibility JSON under `/step-templates` * The *library website* is largely under `/app`, with build artifacts at the root of the repository * The `/tools` folder contains utilities to help with editing step templates @@ -20,7 +20,16 @@ Reviewing PRs ### Reviewing script changes -Step template JSON files embed scripts as single-line escaped strings, making diffs hard to read. Use the `_diff.ps1` tool to extract old and new scripts into separate files you can compare in your diff tool: +Step template scripts now live beside `metadata.json` as normal source files, so diffs are readable in GitHub and in local tools: + +- `scriptbody.ps1` +- `scriptbody.sh` +- `scriptbody.py` + +> [!NOTE] +> This repository previously stored script content only inside `step-templates/*.json` as escaped strings. The source-first layout keeps editable script content under `src/step-templates/