From 02725a09176d5ee19e93b8b076682d10370086d6 Mon Sep 17 00:00:00 2001 From: brandom Date: Fri, 7 Aug 2026 15:37:55 -0700 Subject: [PATCH 1/4] Prepare public-first contribution docs Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 33 +++++++++++++++++++++------------ README.md | 4 +++- 2 files changed, 24 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e320f1aaa..5f3145859 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,29 +1,39 @@ # Contributing to Microsoft Foundry Samples -This repository contains official Microsoft Foundry documentation samples. The contents are published automatically from a private staging repository and are not edited directly here. +> [!IMPORTANT] +> **Transition draft:** These direct-public instructions describe the target contribution path after the public-first cutover. Until this draft pull request is merged, the instructions on the `main` branch remain current. Maintainers must remove this notice only after the cutover gates in the pull request are proven. + +This repository contains official Microsoft Foundry documentation samples. Changes are submitted as pull requests directly to this repository. ## Reporting Issues If you find a bug, have a question, or want to suggest an improvement to an existing sample, please [open an issue](https://github.com/microsoft-foundry/foundry-samples/issues/new) on this repository. We welcome feedback from everyone! -## Contributing Changes (Microsoft Contributors) +Before starting a substantial change, check for an existing issue. Open one when discussion or design agreement would help avoid duplicate work. + +## Contributing Changes -Sample contributions are currently limited to Microsoft Foundry teams. +1. **Create a branch.** Contributors with write access can create a branch in this repository. Other contributors should fork the repository and create a branch in their fork. +2. **Make a focused change.** Keep each pull request scoped to one sample, fix, or related set of updates. Follow the conventions in the surrounding sample. +3. **Respect file ownership.** Review [CODEOWNERS](.github/CODEOWNERS) before editing. The listed owners will be requested when their files are changed. +4. **Validate locally.** Run the setup, build, test, or sample-specific validation documented by the affected sample. Never commit credentials, local environment files, or generated secrets. +5. **Open a pull request against `main`.** Explain what changed, why it changed, and the validation you ran. Link the relevant issue when one exists. -All changes — new samples, updates, and bug fixes — are submitted through the private staging repository [`foundry-samples-pr`](https://github.com/microsoft-foundry/foundry-samples-pr). Changes merged there are automatically synced to this public repository on a nightly basis. +### Pull request checks -> [!NOTE] -> The link above will return a **404** until you've completed step 1 below. +Pull requests run repository validation automatically: -### How to get started +- Changes under `samples/` are detected and validated to the repository's supported build-readiness level. +- Pull requests from forks run without repository credentials. The required `trusted` check is expected to remain blocked until a maintainer promotes the exact commit to a same-repository branch for trusted validation. +- Documentation-only pull requests from same-repository branches satisfy the required check without running sample validation. -1. **Join the `microsoft-foundry` GitHub organization.** Navigate to the organization page on the Open Source Management Portal and click **Join**: +Do not add credentials to a pull request or ask for secrets to be exposed to a fork. A maintainer will handle trusted validation when promotion is required. - +### Temporary workflow-dependent contributions -2. **Access the staging repository.** Once you've joined the org, you'll be able to view [`foundry-samples-pr`](https://github.com/microsoft-foundry/foundry-samples-pr). +Direct public pull requests are the normal contribution path. During the transition, a maintainer may direct a Microsoft contributor to temporary staging for a workflow-dependent change. Use that path only when explicitly requested. -3. **Follow the contributing guide there.** The `foundry-samples-pr` repository has its own [`CONTRIBUTING.md`](https://github.com/microsoft-foundry/foundry-samples-pr/blob/main/CONTRIBUTING.md) with full instructions for setting up write access, creating a branch, and submitting a pull request. +If temporary promotion fails, maintainers use an exact manual public pull request as the fallback. Contributors should not create duplicate publication attempts or alternate versions of the change. ## Contributor License Agreement @@ -32,4 +42,3 @@ This project requires a Contributor License Agreement (CLA). When you submit a p ## Code of Conduct This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com). - diff --git a/README.md b/README.md index 3ca3252ff..7ff587a15 100644 --- a/README.md +++ b/README.md @@ -10,5 +10,7 @@ Use the samples in this repository to try out Microsoft Foundry scenarios on you Found a bug or have a suggestion? [Open an issue](https://github.com/microsoft-foundry/foundry-samples/issues/new) — we welcome feedback from everyone! -Sample contributions are submitted through a private staging repository. If you're a Microsoft employee or contractor, see the [contributing guidelines](CONTRIBUTING.md) for how to get started. +> [!IMPORTANT] +> **Transition draft:** The direct-public contribution path below is proposed for the public-first cutover. Until this draft pull request is merged, follow the contribution instructions on the `main` branch. Maintainers must remove this notice only after the cutover gates in the pull request are proven. +To contribute a sample or fix, open a pull request directly in this repository. See the [contributing guidelines](CONTRIBUTING.md) for setup, validation, and review details. From 8fcc92680952437ea1bc7dec93509ee883cb005b Mon Sep 17 00:00:00 2001 From: brandom Date: Fri, 7 Aug 2026 15:46:22 -0700 Subject: [PATCH 2/4] Clarify supported sample validation coverage Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f3145859..7d57a74d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,8 +23,8 @@ Before starting a substantial change, check for an existing issue. Open one when Pull requests run repository validation automatically: -- Changes under `samples/` are detected and validated to the repository's supported build-readiness level. -- Pull requests from forks run without repository credentials. The required `trusted` check is expected to remain blocked until a maintainer promotes the exact commit to a same-repository branch for trusted validation. +- Supported changed samples under `samples/` are detected and validated to the repository's supported build-readiness level. +- Pull requests from forks run without repository credentials. The required `trusted` check runs and fails until a maintainer promotes the exact head commit to a same-repository branch for trusted validation. - Documentation-only pull requests from same-repository branches satisfy the required check without running sample validation. Do not add credentials to a pull request or ask for secrets to be exposed to a fork. A maintainer will handle trusted validation when promotion is required. From f0f24d0d59829a3d8f03e44352ca973395bfae7a Mon Sep 17 00:00:00 2001 From: brandom Date: Fri, 7 Aug 2026 15:52:15 -0700 Subject: [PATCH 3/4] Tighten validation coverage wording Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d57a74d7..d944a574f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,8 +23,8 @@ Before starting a substantial change, check for an existing issue. Open one when Pull requests run repository validation automatically: -- Supported changed samples under `samples/` are detected and validated to the repository's supported build-readiness level. -- Pull requests from forks run without repository credentials. The required `trusted` check runs and fails until a maintainer promotes the exact head commit to a same-repository branch for trusted validation. +- Supported changed samples are detected and validated automatically. Validation coverage varies by language and sample; review the checks reported on your pull request. +- Fork pull requests run credential-free checks but cannot satisfy the required `trusted` validation directly. A maintainer must promote the exact commit to a same-repository branch. - Documentation-only pull requests from same-repository branches satisfy the required check without running sample validation. Do not add credentials to a pull request or ask for secrets to be exposed to a fork. A maintainer will handle trusted validation when promotion is required. From 2ab6daf109c9e00faf3513061506041bfb4d4f9d Mon Sep 17 00:00:00 2001 From: brandom Date: Thu, 13 Aug 2026 14:12:38 -0700 Subject: [PATCH 4/4] Document public-only contribution routing Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 23 +++++++---------------- README.md | 5 +---- 2 files changed, 8 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d944a574f..adf83aa2d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,5 @@ # Contributing to Microsoft Foundry Samples -> [!IMPORTANT] -> **Transition draft:** These direct-public instructions describe the target contribution path after the public-first cutover. Until this draft pull request is merged, the instructions on the `main` branch remain current. Maintainers must remove this notice only after the cutover gates in the pull request are proven. - This repository contains official Microsoft Foundry documentation samples. Changes are submitted as pull requests directly to this repository. ## Reporting Issues @@ -13,27 +10,21 @@ Before starting a substantial change, check for an existing issue. Open one when ## Contributing Changes -1. **Create a branch.** Contributors with write access can create a branch in this repository. Other contributors should fork the repository and create a branch in their fork. +Sample contributions are currently limited to Microsoft Foundry teams with permission to create a branch in this repository. Fork pull requests cannot satisfy the intentionally failing `trusted` gate, so sample changes must use a same-repository branch. + +1. **Create a branch in this repository.** Use a same-repository branch for all sample changes. 2. **Make a focused change.** Keep each pull request scoped to one sample, fix, or related set of updates. Follow the conventions in the surrounding sample. 3. **Respect file ownership.** Review [CODEOWNERS](.github/CODEOWNERS) before editing. The listed owners will be requested when their files are changed. 4. **Validate locally.** Run the setup, build, test, or sample-specific validation documented by the affected sample. Never commit credentials, local environment files, or generated secrets. -5. **Open a pull request against `main`.** Explain what changed, why it changed, and the validation you ran. Link the relevant issue when one exists. +5. **Open a pull request against `main`.** In the pull request description, explain what changed, why it changed, and the local validation you ran. Link the relevant issue when one exists. ### Pull request checks Pull requests run repository validation automatically: -- Supported changed samples are detected and validated automatically. Validation coverage varies by language and sample; review the checks reported on your pull request. -- Fork pull requests run credential-free checks but cannot satisfy the required `trusted` validation directly. A maintainer must promote the exact commit to a same-repository branch. -- Documentation-only pull requests from same-repository branches satisfy the required check without running sample validation. - -Do not add credentials to a pull request or ask for secrets to be exposed to a fork. A maintainer will handle trusted validation when promotion is required. - -### Temporary workflow-dependent contributions - -Direct public pull requests are the normal contribution path. During the transition, a maintainer may direct a Microsoft contributor to temporary staging for a workflow-dependent change. Use that path only when explicitly requested. - -If temporary promotion fails, maintainers use an exact manual public pull request as the fallback. Contributors should not create duplicate publication attempts or alternate versions of the change. +- The required `trusted` check must pass. +- Review and address the other checks reported on the pull request. +- After required checks and review are complete, a maintainer triggers the merge. Pull requests are not merged automatically. ## Contributor License Agreement diff --git a/README.md b/README.md index 7ff587a15..a6d5db521 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,4 @@ Use the samples in this repository to try out Microsoft Foundry scenarios on you Found a bug or have a suggestion? [Open an issue](https://github.com/microsoft-foundry/foundry-samples/issues/new) — we welcome feedback from everyone! -> [!IMPORTANT] -> **Transition draft:** The direct-public contribution path below is proposed for the public-first cutover. Until this draft pull request is merged, follow the contribution instructions on the `main` branch. Maintainers must remove this notice only after the cutover gates in the pull request are proven. - -To contribute a sample or fix, open a pull request directly in this repository. See the [contributing guidelines](CONTRIBUTING.md) for setup, validation, and review details. +Microsoft contributors with permission to create a branch in this repository can contribute a sample or fix by opening a pull request directly against `main`. Pull requests must pass the required `trusted` check and are merged by a maintainer. See the [contributing guidelines](CONTRIBUTING.md) for setup, validation, and review details.