From d17ca4db4391eb6fed7cc475ca32c28a7287d10a Mon Sep 17 00:00:00 2001 From: Apollo Kariuki Date: Fri, 31 Jul 2026 20:04:03 +0300 Subject: [PATCH 1/3] docs: supercharge repository AI-readiness (automated) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../instructions/ci-workflows.instructions.md | 13 ++ .github/instructions/content.instructions.md | 13 ++ .github/instructions/tests.instructions.md | 12 ++ .github/pull_request_template.md | 15 ++ .gitignore | 11 ++ AGENTS.md | 57 +++++++ CONTRIBUTING.md | 55 ++++++ README.md | 15 ++ repo-context.md | 161 ++++++++++++++++++ 9 files changed, 352 insertions(+) create mode 100644 .github/instructions/ci-workflows.instructions.md create mode 100644 .github/instructions/content.instructions.md create mode 100644 .github/instructions/tests.instructions.md create mode 100644 .github/pull_request_template.md create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md create mode 100644 repo-context.md diff --git a/.github/instructions/ci-workflows.instructions.md b/.github/instructions/ci-workflows.instructions.md new file mode 100644 index 00000000..787350ce --- /dev/null +++ b/.github/instructions/ci-workflows.instructions.md @@ -0,0 +1,13 @@ +--- +applyTo: '.github/workflows/*.yml' +--- +# GitHub Actions Instructions + +**When to read:** Editing GitHub Actions workflows. + +- When changing validation scope, update the same path set in `validate.yml` `paths` and `validate-patch.yml` `paths-ignore`: the canonical sample catalog, `scripts/**`, `tests/**`, and both npm manifest files. +- Preserve the `validate-json-schema` and `test` job names in both validation workflows because the patch workflow supplies their stand-in results. +- Keep the Jest `test` job dependent on `validate-json-schema` in `.github/workflows/validate.yml`. +- In the translation handoff, preserve the staging step that collects localized files before opening the cross-repository pull request. +- Reference credentials through GitHub Actions secrets, following `.github/workflows/handover-translations.yml`; never inline credential values. +- Get explicit approval before changing triggers, required-check behavior, permissions, secrets, or cross-repository handoff destinations. diff --git a/.github/instructions/content.instructions.md b/.github/instructions/content.instructions.md new file mode 100644 index 00000000..609f6912 --- /dev/null +++ b/.github/instructions/content.instructions.md @@ -0,0 +1,13 @@ +--- +applyTo: 'sample-queries/**,permissions/**,messages/**,ge-tour/**' +--- +# Content Catalog Instructions + +**When to read:** Editing Graph Explorer or DevX content catalogs. + +- In `sample-queries/sample-queries.json`, keep fields in the order documented in `README.md`: `id`, `category`, `method`, `humanName`, `requestUrl`, `docLink`, `headers`, `postBody`, `tip`, then `skipTest` when applicable. +- A sample with `postBody` must also define `headers`; JSON request bodies are parsed by `tests/validator.js` unless the content type is XML. +- Keep `skipTest` false for sample queries, as required by `README.md`. +- Permission display names in `permissions/permissions-descriptions.json` must not have leading or trailing spaces or end with a period. +- Documentation links are checked with network HEAD requests, so distinguish an unavailable endpoint from a malformed catalog entry. +- Avoid unrelated catalog reformatting or reordering because these files are published for external consumers. diff --git a/.github/instructions/tests.instructions.md b/.github/instructions/tests.instructions.md new file mode 100644 index 00000000..bd887cd5 --- /dev/null +++ b/.github/instructions/tests.instructions.md @@ -0,0 +1,12 @@ +--- +applyTo: 'tests/**' +--- +# Test Instructions + +**When to read:** Editing validation specifications, validators, or schemas under `tests/`. + +- Jest specifications use the `.spec.js` suffix and load canonical catalogs from `sample-queries/sample-queries.json` or `permissions/permissions-descriptions.json`. +- Keep sample structure rules aligned between `tests/samples.schema.json` and `tests/samples.spec.js`. +- `tests/samples.spec.js` validates documentation links with network HEAD requests through `tests/validator.js`; distinguish endpoint failures from assertion failures. +- Run `npm run test` after test or validator changes. +- Do not weaken GUID, URL, request-body, display-name, or documentation-link checks merely to accept invalid content. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..a0486872 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## Description + +Describe the change, its purpose, and any related issue. + +## Testing Done + +List the validation performed and the results. Explain why testing is not applicable when relevant. + +## Checklist + +- [ ] The change is scoped to the intended content or configuration. +- [ ] Applicable tests were added or updated and pass. +- [ ] Applicable documentation was updated. +- [ ] Breaking changes and consumer impact are described. +- [ ] No secrets or sensitive data are included. diff --git a/.gitignore b/.gitignore index 3c3629e6..d38c7207 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,12 @@ node_modules + +# Local environment and secret files +.env +.env.* +!.env.example +*.pem +*.key +*.pfx +*.p12 +credentials.json +service-account*.json diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..1f21a7b7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,57 @@ +# AGENTS.md + +## Build & Test + +See `CONTRIBUTING.md` for setup, test, and verification commands. + +## Environment Constraints + +See `CONTRIBUTING.md` for toolchain and runtime requirements. + +## Operational Context + +Before answering questions or making changes, read: + +- `repo-context.md` - Repository structure, content flow, configuration, dependencies, and ownership. +- `CONTRIBUTING.md` - Setup, validation, contribution workflow, and common pitfalls. +- `README.md` - Canonical sample-query and permission authoring requirements. + +This repository publishes content rather than running an application service. Validation and publication are separate: `.github/workflows/validate.yml` runs schema and Jest checks, while `azure-pipelines/publishSamples.yml` publishes selected content from `master`. + +## Safety Guardrails + +> **WARNING:** Production publication and cross-repository handoff are destructive or externally visible operations. Always get explicit user approval before: +> - Running or changing the production publication behavior in `azure-pipelines/publishSamples.yml`. +> - Running or changing the translation handoff behavior in `.github/workflows/handover-translations.yml`. +> - Changing protected-branch, required-check, credential, or secret handling. + +### Rules + +- Never force push, run `git reset --hard`, or rewrite shared branch history. +- Never deploy or publish content without explicit user approval. +- Never weaken validation, branch protection, review, or security controls to make a change pass. +- Keep edits scoped to the requested content area; avoid unrelated reformatting of large JSON catalogs. +- Treat `permissions/new/` as a separate data model from `permissions/permissions-descriptions.json`. + +## Secrets Management + +GitHub Actions accesses credentials through repository secrets in `.github/workflows/handover-translations.yml`, including `API_TOKEN_GITHUB`, `ACTION_EMAIL`, and `ACTION_USERNAME`. + +### Rules for AI Agents + +- Never inline secrets, tokens, passwords, connection strings, certificate material, or secret values. +- Never commit `.env`, credential, key, certificate, or token files. +- Preserve the existing `${{ secrets.NAME }}` reference pattern in GitHub Actions. +- Do not print, retrieve, rotate, or replace repository secrets without explicit user approval. + +## PR Workflow + +When creating pull requests, read and follow `.github/pull_request_template.md`. Complete the description, testing, and checklist sections. Mark a section N/A when it does not apply rather than removing it. + +## Test Selection + +Jest 29.3.1 is the test framework declared in `package.json`. Keep `--no-watch` in local targeted commands so the repository test launcher terminates. + +- Run one test file by path: `npm run test -- --no-watch --runTestsByPath tests/permissions-descriptions.spec.js` +- Run one named test in that file: `npm run test -- --no-watch --runTestsByPath tests/permissions-descriptions.spec.js --testNamePattern "^Permissions descriptions consistency TenantGovernance-Invitation[.]ReadWrite[.]All: adminConsentDisplayName should not have trailing spaces$"` +- For another test, replace the quoted regular expression with its full Jest test name. Include the enclosing `describe` names when they are needed to select exactly one generated test. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..a68e0a35 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing + +The repository already documents its content-authoring rules in `README.md`. Use those instructions as the canonical source rather than duplicating them here: + +- [Adding Sample Queries](README.md#adding-sample-queries) +- [Testing of Sample Queries](README.md#testing-of-sample-queries) +- [Adding Permissions](README.md#adding-permissions) + +## Quick Start + +1. Complete the prerequisites and fork or clone steps in [Adding Sample Queries](README.md#adding-sample-queries). +2. Install the npm dependencies. The validation workflow uses `npm install`. +3. Make the content change using the field, naming, and ordering rules in `README.md`. +4. Run `npm run test` before opening a pull request. + +Permission contributions are limited to contributors with write access. Other contributors can report missing permissions through the repository issue tracker linked from [Adding Permissions](README.md#adding-permissions). + +## Returning Developer Fast Path + +Pull the latest `master`, install dependencies if `package.json` or `package-lock.json` changed, make the content update, and run `npm run test`. For sample-query changes, also use the branch-specific Graph Explorer URL described in [Testing of Sample Queries](README.md#testing-of-sample-queries). + +## Common Pitfalls + +- Editing a localized file when the intended change belongs in the unsuffixed canonical JSON file. +- Treating `permissions/new/` as interchangeable with `permissions/permissions-descriptions.json`; they use different data models. +- Omitting the sample-query property order, lowercase `humanName` rule, relative request URL, or required documentation link described in `README.md` and checked by validation. +- Assuming no CI check is required when a change falls outside the paths watched by `validate.yml`; `validate-patch.yml` supplies the required successful status for those pull requests. +- Forgetting that sample documentation links are checked with network requests, so local test results can depend on endpoint availability. + +## Contribution Workflow + +1. Create a branch using the initials-and-purpose format documented in `README.md`. +2. Keep changes scoped to the relevant content area and update canonical and localized files only when the change requires both. +3. Run the applicable local validation and inspect the changed JSON for accidental formatting or unrelated content changes. +4. Push the branch and open a pull request against the appropriate protected branch. +5. Wait for validation and review. The branch policy requires pull requests, one approving review, and strict status checks for `master` and `dev`. +6. Address review feedback with additional commits. New commits dismiss stale approvals on `master`. + +Repository-wide code ownership is assigned to `@microsoftgraph/msgraph-devx-api-write` through `.github/CODEOWNERS`. + +## Who to Ask + +Use the repository issue tracker for content gaps and questions that should be publicly tracked. For review routing, use the repository-wide CODEOWNERS team. The existing contact list for contribution issues remains in the final paragraph of `README.md`. + +## Building + +This is a static content repository, so it does not produce a compiled application or a separate build artifact. The Jest validation suite is the build check. The `test` script is defined in `package.json` and launches `scripts/test-initiator.js`. + +For a validation run that terminates instead of entering local watch mode, run `npm run test -- --no-watch`. The `--no-watch` behavior is implemented in `scripts/test-initiator.js`. This command was validated in the current checkout with Node.js v24.14.1 and npm 11.11.0; it completed successfully with exit code 0. + +In CI mode, set `CI=true` and run `npm run test`. For PowerShell, the validated form is `$env:CI='true'; npm run test`. The CI condition is defined in `scripts/test-initiator.js`, and the repository workflow runs `npm run test` in `.github/workflows/validate.yml`. The PowerShell form completed successfully with exit code 0 in the current checkout. + +## Running + +There is no local application service to start. Exercise a content change by running the terminating validation command in [Building](#building). For sample-query changes, use the branch-specific Graph Explorer workflow in [Testing of Sample Queries](README.md#testing-of-sample-queries) after local validation passes. diff --git a/README.md b/README.md index f9fdc1c1..326bb06c 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ Content used by the DevX API to enhance clients and tooling. At the moment it ha This will also be used by the localization team to add translation files, and by feature teams to modify, add, or update samples. +See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, build, test, and usage instructions. + ## Contributing ## Adding Sample Queries @@ -161,3 +163,16 @@ Contributions to permissions are limited to contributors with write access. Howe In case you see *You are viewing a cached set of samples because of a network connection failure*, check the query parameters and confirm they're correct, then reload the page. If you run into any issues, reach out to @MaggieKimani1, @irvinesunday or @thewahome. + +## Documentation + +| Document | Description | +|----------|-------------| +| [Repository Context](repo-context.md) | Repository structure, content areas, configuration, dependencies, integrations, and conventions. | +| [Contributing Guide](CONTRIBUTING.md) | Setup, validation, and contribution workflow. | +| [Agent Guidance](AGENTS.md) | Repository-wide guidance and safety rules for AI agents. | +| [Code of Conduct](CODE_OF_CONDUCT.md) | Community standards and conduct resources. | +| [Pull Request Template](.github/pull_request_template.md) | Required pull request description, testing details, and checklist. | +| [CI Workflow Instructions](.github/instructions/ci-workflows.instructions.md) | Scoped guidance for GitHub Actions workflow changes. | +| [Content Catalog Instructions](.github/instructions/content.instructions.md) | Scoped guidance for content catalog changes. | +| [Test Instructions](.github/instructions/tests.instructions.md) | Scoped guidance for validation and test changes. | diff --git a/repo-context.md b/repo-context.md new file mode 100644 index 00000000..a6fce329 --- /dev/null +++ b/repo-context.md @@ -0,0 +1,161 @@ +# microsoft-graph-devx-content Repository Context + +> **Microsoft Graph DevX content** +> +> This repository stores content consumed by the DevX API and Graph Explorer, including sample queries, permission metadata, localized messages, and guided-tour content. Validation runs in Node.js, while GitHub Actions and Azure Pipelines validate and distribute selected content. + +## Repository at a Glance + +| Attribute | Value | +|-----------|-------| +| Languages | JSON content, JavaScript validation code, YAML pipeline definitions, and Markdown documentation | +| Frameworks | Jest test runner and JSON Schema validation | +| Build system | npm scripts, with `npm run test` as the validation entry point | +| Test framework | Jest, plus the `dsanders11/json-schema-validate-action` GitHub Action | +| Source control | GitHub repository `chegeapollo11/microsoft-graph-devx-content`, default branch `master` | +| Package management | npm with `package.json` and `package-lock.json` | +| Scale | A content repository organized into several independently maintained data areas, validation scripts, and CI/CD definitions | + +--- + +## Top-Level Directory Map + +```text +microsoft-graph-devx-content/ +|-- .github/ # Code ownership, branch policy, and GitHub Actions workflows +|-- azure-pipelines/ # Production content publication pipeline +|-- ge-tour/ # Graph Explorer guided-tour steps +|-- messages/ # Base and localized Graph Explorer message dictionaries +|-- permissions/ # Permission descriptions and newer permission/provisioning models +|-- sample-queries/ # Base and localized Graph Explorer sample query catalogs +|-- scripts/ # Node.js test launcher +`-- tests/ # Jest specifications, validators, and sample-query JSON Schema +``` + +--- + +## Source Code Structure + +### Feature Areas + +| Directory | Description | +|-----------|-------------| +| `sample-queries/` | Stores the base `sample-queries.json` catalog and locale-suffixed translations used for Graph Explorer samples. | +| `permissions/` | Stores the permission description catalog and localized variants. The `permissions/new/` subtree contains permission path mappings and deployment metadata in a different model. | +| `messages/` | Stores the base `GE.json` message dictionary and locale-suffixed translations handed to Graph Explorer. | +| `ge-tour/` | Stores the structured guided-tour steps shown by Graph Explorer. | + +### Other Source Directories + +| Directory | Purpose | +|-----------|---------| +| `scripts/` | Starts Jest with repository-aware watch behavior and test environment variables. | +| `tests/` | Validates sample-query structure, identifiers, URLs, document links, request bodies, and permission-description formatting. | +| `.github/workflows/` | Validates changes and transfers translated messages to the Graph Explorer repository. | +| `azure-pipelines/` | Copies sample-query and permission artifacts and uploads them to production Azure Blob Storage. | + +--- + +## Key Directory Disambiguations + +- `sample-queries/` vs `messages/` - sample query records describe executable Microsoft Graph requests, while message files are UI localization dictionaries. +- `permissions/permissions-descriptions.json` vs `permissions/new/permissions.json` - the former is a list of display and consent descriptions; the latter maps permission schemes to Microsoft Graph paths and methods. +- `permissions/new/permissions.json` vs `permissions/new/provisioningInfo.json` - permission definitions and path sets are separate from environment-specific permission deployment metadata. +- `.github/workflows/validate.yml` vs `.github/workflows/validate-patch.yml` - the first performs validation for relevant changes; the second supplies successful required checks when a pull request does not touch validation-scoped paths. + +--- + +## Component Layering Conventions + +The repository follows a content pipeline rather than an application service layering model: + +1. Authors update canonical or localized JSON content under the feature directories. +2. `tests/samples.schema.json` and the Jest specifications under `tests/` validate the sample-query and permission content through `scripts/test-initiator.js`. +3. `.github/workflows/validate.yml` runs schema validation and the npm test suite for relevant pull requests and pushes. +4. `azure-pipelines/publishSamples.yml` packages sample-query and permission files and uploads them to Azure Blob Storage from `master`. +5. `.github/workflows/handover-translations.yml` copies translated `messages/GE_*` files to `microsoftgraph/microsoft-graph-explorer-v4` from the `dev` branch. +6. The DevX API and Graph Explorer consume the published content, as described in `README.md`. + +--- + +## File Naming Conventions + +- The unsuffixed JSON file is the base content file, such as `GE.json`, `sample-queries.json`, or `permissions-descriptions.json`. +- Localized files append an underscore and locale code before `.json`, such as `_de-DE`, `_fr-FR`, or `_zh-CN`. +- Jest test files use the `.spec.js` suffix. +- GitHub workflow file names describe their action, such as `validate.yml`, `validate-patch.yml`, and `handover-translations.yml`. + +--- + +## Configuration Systems + +| System | Type | Key Files | Notes | +|--------|------|-----------|-------| +| Content catalogs | JSON documents | `sample-queries/sample-queries.json`, `permissions/permissions-descriptions.json`, `permissions/new/permissions.json`, `permissions/new/provisioningInfo.json`, `messages/GE.json`, `ge-tour/tour-steps.json` | Canonical and localized data consumed outside this repository. | +| Validation configuration | npm script and JSON Schema | `package.json`, `tests/samples.schema.json`, `scripts/test-initiator.js` | `npm run test` starts Jest; GitHub Actions separately validates the sample catalog against its schema. | +| GitHub automation | GitHub Actions YAML | `.github/workflows/validate.yml`, `.github/workflows/validate-patch.yml`, `.github/workflows/handover-translations.yml` | Path filters select validation or translation handoff behavior. | +| Publication automation | Azure Pipelines YAML | `azure-pipelines/publishSamples.yml` | Packages sample-query and permission content and publishes it to Azure Blob Storage. | +| Branch governance | Repository policy YAML and CODEOWNERS | `.github/policies/microsoft-graph-devx-content-branch-protection.yml`, `.github/CODEOWNERS` | Protects `master` and `dev` and assigns repository-wide ownership. | + +### Config Disambiguation + +- `package.json` defines the local test command and development dependencies; `tests/samples.schema.json` defines the allowed shape of sample-query content. +- GitHub Actions validate pull requests and hand off translations; `azure-pipelines/publishSamples.yml` handles production artifact publication. + +--- + +## Key Entry Points + +- `package.json` - maps `npm run test` to `scripts/test-initiator.js`. +- `scripts/test-initiator.js` - sets the test environment and starts Jest. +- `tests/samples.spec.js` - exercises each entry in the canonical sample-query catalog. +- `tests/permissions-descriptions.spec.js` - checks display-name formatting in the canonical permission descriptions. +- `.github/workflows/validate.yml` - CI entry point for schema and Jest validation. +- `azure-pipelines/publishSamples.yml` - production publication entry point for sample-query and permission files. +- `.github/workflows/handover-translations.yml` - translation handoff entry point for localized Graph Explorer messages. + +--- + +## Dependencies and Integrations + +### Internal Dependencies + +| Package/Library | Purpose | Owner | +|----------------|---------|-------| +| Jest | Runs the JavaScript validation specifications. | Not declared in this repository | +| `node-fetch` | Sends HEAD requests when validating sample documentation links. | Not declared in this repository | +| `tests/samples.schema.json` | Defines the structural contract for `sample-queries/sample-queries.json`. | `@microsoftgraph/msgraph-devx-api-write` | + +### External Services + +| Service | Purpose | Owner | +|---------|---------|-------| +| Microsoft Graph Explorer | Presents repository samples, permissions, messages, and tour content to users. | Not declared in this repository | +| DevX API | Serves repository content to clients and tooling. | Not declared in this repository | +| Azure Blob Storage | Receives published sample-query and permission artifacts from the production pipeline. | Not declared in this repository | +| Microsoft Graph documentation endpoints | Supply the `docLink` targets checked by the sample validation suite. | Not declared in this repository | + +### Related Repositories + +| Repo | Relationship | Purpose | +|------|-------------|---------| +| `microsoftgraph/microsoft-graph-explorer-v4` | Receives translated message files through `.github/workflows/handover-translations.yml`. | Hosts the Graph Explorer application that consumes the content. | + +--- + +## Team Ownership + +| Team | Primary Code Areas | +|------|--------------------| +| `@microsoftgraph/msgraph-devx-api-write` | The repository-wide `*` rule in `.github/CODEOWNERS` assigns all paths to this team. | + +--- + +## Key Conventions for Agents + +1. Preserve the sample-query property order and field rules documented in `README.md`. +2. Keep sample `humanName` values lowercased at the first word and use relative `/v1.0` or `/beta` request URLs, matching the Jest validations. +3. Add locale-specific content by following the existing `_.json` naming pattern. +4. Run `npm run test` for changes covered by the JavaScript validation suite; sample-query changes are also schema-validated in GitHub Actions. +5. Do not bypass pull requests for `master` or `dev`; both branches require a pull request and one approving review according to the branch policy. +6. Treat `permissions/new/` as a distinct data model from the localized permission-description files at the parent directory level. From 38a17382e53bb3692ca2bbb9e725b88efc1ce80f Mon Sep 17 00:00:00 2001 From: Apollo Kariuki Date: Sun, 2 Aug 2026 23:35:15 +0300 Subject: [PATCH 2/3] Update upstream repository name. --- repo-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/repo-context.md b/repo-context.md index a6fce329..b871b114 100644 --- a/repo-context.md +++ b/repo-context.md @@ -12,7 +12,7 @@ | Frameworks | Jest test runner and JSON Schema validation | | Build system | npm scripts, with `npm run test` as the validation entry point | | Test framework | Jest, plus the `dsanders11/json-schema-validate-action` GitHub Action | -| Source control | GitHub repository `chegeapollo11/microsoft-graph-devx-content`, default branch `master` | +| Source control | GitHub repository `microsoftgraph/microsoft-graph-devx-content`, default branch `master` | | Package management | npm with `package.json` and `package-lock.json` | | Scale | A content repository organized into several independently maintained data areas, validation scripts, and CI/CD definitions | From d5ba8b38866750c553ba49bc1dcc1096efb33d5f Mon Sep 17 00:00:00 2001 From: Apollo Kariuki Date: Thu, 6 Aug 2026 07:49:07 +0300 Subject: [PATCH 3/3] docs: address Copilot review comments in repo-context - Mark jest and node-fetch as declared in package.json devDependencies (they were incorrectly listed as 'Not declared in this repository'). - Align humanName guidance with the canonical README rule (small caps only / all lowercase) instead of the ambiguous 'lowercased at the first word'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- repo-context.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/repo-context.md b/repo-context.md index b871b114..4d2043df 100644 --- a/repo-context.md +++ b/repo-context.md @@ -122,8 +122,8 @@ The repository follows a content pipeline rather than an application service lay | Package/Library | Purpose | Owner | |----------------|---------|-------| -| Jest | Runs the JavaScript validation specifications. | Not declared in this repository | -| `node-fetch` | Sends HEAD requests when validating sample documentation links. | Not declared in this repository | +| Jest | Runs the JavaScript validation specifications. | Declared in `package.json` `devDependencies`. | +| `node-fetch` | Sends HEAD requests when validating sample documentation links. | Declared in `package.json` `devDependencies`. | | `tests/samples.schema.json` | Defines the structural contract for `sample-queries/sample-queries.json`. | `@microsoftgraph/msgraph-devx-api-write` | ### External Services @@ -154,7 +154,7 @@ The repository follows a content pipeline rather than an application service lay ## Key Conventions for Agents 1. Preserve the sample-query property order and field rules documented in `README.md`. -2. Keep sample `humanName` values lowercased at the first word and use relative `/v1.0` or `/beta` request URLs, matching the Jest validations. +2. Keep sample `humanName` values in small caps only (all lowercase), per the canonical rule in `README.md`, and use relative `/v1.0` or `/beta` request URLs matching the Jest validations. 3. Add locale-specific content by following the existing `_.json` naming pattern. 4. Run `npm run test` for changes covered by the JavaScript validation suite; sample-query changes are also schema-validated in GitHub Actions. 5. Do not bypass pull requests for `master` or `dev`; both branches require a pull request and one approving review according to the branch policy.