github-community-projects / github-community-projects/safe-settings
TeamSettings schema missing include/exclude repo filter declarations
- Dominant language
- JavaScript
- Stars
- 921
- Forks
- 226
- Avg merge
- 18h 3m
- Merged PRs (30d)
- 14
Description
## Prerequisites:
* Is the functionality available in the GitHub UI? If so, please provide a link to information about the feature.
N/A — this request is for schema validation and documentation of an existing safe-settings feature, not a new GitHub API capability.
* Is the functionality available through the GitHub API? If the functionality is available, please provide links to the API documentation (https://developer.github.com/v3/) as well as the Octokit documentation (https://octokit.github.io/).
N/A — `include`/`exclude` repo filtering is internal safe-settings logic (the `Diffable` class), not a GitHub API concept. The filtering already works at runtime for `teams` entries; it is simply not declared in the schema or covered in the documentation.
## New Feature
The `teams` section of a safe-settings configuration already supports `include` and `exclude` repo filters at runtime via the same `Diffable` logic used by `collaborators`. However, unlike `collaborators`, these keys are not declared in the `TeamSettings` JSON schema and are not documented in the teams guide.
This means:
- Editors and linters that validate configuration files against the schema report `include`/`exclude` as unknown properties on team entries, even though they are valid and functional.
- There is no official documentation or example showing users how to use per-repo filtering for teams.
Please describe the desired new functionality:
1. The `TeamSettings` definition in `schema/repos.json`, `schema/settings.json`, and `schema/suborgs.json` (and their dereferenced counterparts) should declare `include` and `exclude` using the same `allOf` pattern already used by `CollaboratorSettings`, so that editors and schema validators accept these fields without warnings.
2. The [teams guide](docs/github-settings/4.%20teams.md) should document `include` and `exclude` with descriptions and YAML examples consistent with the collaborators guide.
3. The [sample settings file](docs/sample-settings/settings.yml) should include representative team entries demonstrating both `include` and `exclude`.
4. Unit tests should cover the include/exclude filter code path for the `Teams` plugin, mirroring the coverage that exists for `Collaborators`.
No changes to runtime logic are required.
Contributor guide
Research direction
Start by comparing the CollaboratorSettings definitions in schema/repos.json, schema/settings.json, schema/suborgs.json and their dereferenced counterparts, then read docs/github-settings/4. teams.md, docs/sample-settings/settings.yml, and the existing Collaborators tests. Done means the schemas accept team include/exclude filters, the teams guide and sample show both forms, and Teams tests cover the filter path.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation, testing-qa
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 70/100