From df5009674f9b6f788023170278f9af210df42a32 Mon Sep 17 00:00:00 2001 From: Josh Johanning Date: Mon, 6 Oct 2025 10:27:44 -0500 Subject: [PATCH 1/4] docs: update copilot instructions --- .github/copilot-instructions.md | 36 +++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a2d4a06..9be4344 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,15 +2,17 @@ ## scripts in the `gh-cli` and `scripts` directories -When creating or modifying scripts in the `gh-cli` directory, ensure: +When creating or modifying scripts in the `gh-cli` directory: -- The script has input parameters -- The script has a basic description and usage examples at the top -- We make sure to paginate (`--paginate`) when retrieving results +- Ensure the script has input parameters +- Ensure the script has a basic description and usage examples at the top +- Make sure to paginate (`--paginate`) when retrieving results - Note any special permissions/token requirements - If modifying input parameters to a script, make sure to update the respective `README.md` in the script directory (if applicable) - Use only `2` spaces for indentation - not `4` - Do not leave any trailing whitespace at the end of lines +- With `gh api` commands, prefer `--jq` versus piping to `jq` when possible +- Include the header `-H "X-Github-Next-Global-ID: 1"` in GraphQL queries to retrieve the new global ID format - see the [GitHub migration guide for global node IDs](https://docs.github.com/en/graphql/guides/migrating-graphql-global-node-ids) for details ## README.md documentation @@ -23,6 +25,8 @@ When adding new scripts to any directory: - Use proper kebab-case naming convention for script files - Avoid short words like "repo" (use "repository"), "org" (use "organization") - Test that the entry passes `lint-readme.js` validation +- Don't be too verbose - keep descriptions and usage instructions concise and to the point +- Don't use periods after bullet points for consistency ## Script naming and structure @@ -39,3 +43,27 @@ When adding new scripts to any directory: - Document required scopes and permissions in script comments - Use environment variables or parameters for sensitive data (never hardcode tokens) - For scripts requiring special permissions, mention this in both script comments and README +- Add hostname support for GitHub Enterprise instances / ghe.com when applicable + +## Commit messages + +Prefer the Conventional Commits specification: + +- Format: `(): ` +- Types: + - `feat`: New feature + - `fix`: Bug fix + - `refactor`: Code change that neither fixes a bug nor adds a feature + - `docs`: Documentation only changes + - `chore`: Changes to build process or auxiliary tools + - `ci`: Changes to CI configuration files and scripts + - `style`: Code style changes (formatting, missing semicolons, etc.) + - `test`: Adding or updating tests +- Scopes (optional): + - `scripts`: Changes in the scripts directory + - `gh-cli`: Changes in the gh-cli directory + - `ci`: Changes to CI/linting tools +- Description: Short, imperative tense summary (e.g., "add feature" not "added feature") +- Body (optional): Provide additional context with bullet points +- Keep it concise but descriptive +- Append `!` to the type if it's a breaking change (e.g., `feat!: add additional required input parameters`) From 0538ebebf29721b3fb41119ffed99efc5d8372e8 Mon Sep 17 00:00:00 2001 From: Josh Johanning Date: Mon, 6 Oct 2025 10:31:04 -0500 Subject: [PATCH 2/4] docs: update copilot instructions --- .github/copilot-instructions.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 9be4344..76836be 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,9 +2,10 @@ ## scripts in the `gh-cli` and `scripts` directories -When creating or modifying scripts in the `gh-cli` directory: +When creating or modifying scripts in the `gh-cli` and `scripts` directories: - Ensure the script has input parameters +- Include input validation and meaningful error messages - Ensure the script has a basic description and usage examples at the top - Make sure to paginate (`--paginate`) when retrieving results - Note any special permissions/token requirements @@ -28,7 +29,7 @@ When adding new scripts to any directory: - Don't be too verbose - keep descriptions and usage instructions concise and to the point - Don't use periods after bullet points for consistency -## Script naming and structure +## script naming and structure - Use kebab-case for all script filenames (e.g., `get-organization-repositories.sh`) - Include appropriate file extensions (.sh, .ps1, .js, .py) @@ -45,7 +46,7 @@ When adding new scripts to any directory: - For scripts requiring special permissions, mention this in both script comments and README - Add hostname support for GitHub Enterprise instances / ghe.com when applicable -## Commit messages +## commit messages Prefer the Conventional Commits specification: From 0236a9396cd24764ea8463a4f0b2b500928e977e Mon Sep 17 00:00:00 2001 From: Josh Johanning Date: Mon, 6 Oct 2025 10:31:34 -0500 Subject: [PATCH 3/4] docs: clarify pagination instructions in copilot guidelines --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 76836be..8fff481 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,7 +7,7 @@ When creating or modifying scripts in the `gh-cli` and `scripts` directories: - Ensure the script has input parameters - Include input validation and meaningful error messages - Ensure the script has a basic description and usage examples at the top -- Make sure to paginate (`--paginate`) when retrieving results +- Make sure to paginate (`--paginate` and/or `octokit.paginate`) when retrieving results - Note any special permissions/token requirements - If modifying input parameters to a script, make sure to update the respective `README.md` in the script directory (if applicable) - Use only `2` spaces for indentation - not `4` From cd6de8f8d709c9c6aa84f5e01b91f06bfe70629f Mon Sep 17 00:00:00 2001 From: Josh Johanning Date: Mon, 6 Oct 2025 10:32:24 -0500 Subject: [PATCH 4/4] docs: add note about folder structure for complex scripts in copilot instructions --- .github/copilot-instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8fff481..787e71f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -14,6 +14,7 @@ When creating or modifying scripts in the `gh-cli` and `scripts` directories: - Do not leave any trailing whitespace at the end of lines - With `gh api` commands, prefer `--jq` versus piping to `jq` when possible - Include the header `-H "X-Github-Next-Global-ID: 1"` in GraphQL queries to retrieve the new global ID format - see the [GitHub migration guide for global node IDs](https://docs.github.com/en/graphql/guides/migrating-graphql-global-node-ids) for details +- Complex scripts in the `./scripts` directory should have its own folder (so a `package.json` can be included for example) ## README.md documentation