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..22fa35cec 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -7,21 +7,23 @@ Have a great custom step that other Octopus users will love? Here's how to get i 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_ +5. Run `node tools/migrate-source-first.js --template [--template ...]` to migrate the selected templates into the source-first layout under `/src/step-templates` +6. Review the generated changes, including the rebuilt compatibility JSON in `/step-templates` +7. Check that the `LastModifiedBy` username is one you're happy to use on the site (ideally your plain GitHub username) +8. 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 +9. 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 a `logo.png` file with a size of 200x200px beside the migrated template under `src/step-templates//`. 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. +10. 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. +11. Commit and push your changes to your fork +12. 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. +> [!NOTE] +> The repository is in a temporary mixed migration state. `step-templates/*.json` remains the compatibility output used by the existing build and publishing workflow, but new template work should migrate the named template into `src/step-templates/**` instead of adding new legacy JSON-first files. -* 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] +> The migration script follows a four-step guided flow and supports one or more selected templates per run. Use `--template-prefix ` when you want to migrate or reset a batch by name prefix. If you need to discard a local migration attempt before committing, run `node tools/migrate-source-first-reset.js --template [--template ...]`. Here's a **checklist** to consider: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9f007c1d4..6d453ff83 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 + - [ ] A `logo.png` file must be present beside the migrated template under `src/step-templates/