Migrate step templates to a source-first layout

.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

.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/<template-name>/`
+5. Author step templates in `/src/step-templates/<template-name>/`, 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:
 

.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_

.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

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/<template>/`, while the legacy JSON remains a generated compatibility output.
+
+If you need to compare the generated JSON with an older branch or commit, you can still use the `_diff.ps1` tool:
 
 ```powershell
 # Compare ScriptBody against previous commit
@@ -34,7 +43,8 @@ This outputs readable files to `diff-output/`:
 - `template-name.ScriptBody.old.ps1`
 - `template-name.ScriptBody.new.ps1`
 
-Also handles `PreDeploy`, `Deploy`, and `PostDeploy` custom scripts if present.
+> [!NOTE]
+> Octopus Deploy still exports step templates as JSON. If you start from an export, save the file under `step-templates/`, run `powershell .\tools\_unpack.ps1 -SearchPattern "template-name"`, then move the resulting `metadata.json` and `scriptbody.*` files into `src/step-templates/<template>/`. Build tooling must continue to generate `step-templates/*.json`; that generated output is the compatibility contract 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.
 
 ### Checklist
 
@@ -45,5 +55,5 @@ When reviewing a PR, keep the following things in mind:
 * The `DefaultValue`s of `Parameter`s should be either a string or null.
 * `LastModifiedBy` field must be present, and (_optionally_) updated with the correct author
 * 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