From 80d39c9560e1a408a6d6e205a044d62395bae565 Mon Sep 17 00:00:00 2001 From: Paul Lizer Date: Fri, 10 Apr 2026 06:15:59 -0400 Subject: [PATCH 1/2] Added contributing support --- CONTRIBUTING.md | 103 ++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++ docs/_config.yml | 3 ++ docs/contributing.md | 110 +++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 4 ++ 5 files changed, 224 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 docs/contributing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..23af1795 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,103 @@ +# Contributing to SimpleChat + +This repository uses the standard `CONTRIBUTING.md` filename so GitHub can surface the guide automatically. +The documentation-site copy lives at `docs/contributing.md`, and both files should stay aligned. + +## Contribution Flow + +SimpleChat contributions should be made through a fork-based workflow. + +1. Fork the repository. +2. Clone your fork locally. +3. Add the main SimpleChat repository as `upstream`. +4. Create a new branch from the upstream `Development` branch. +5. Make your changes in that new branch. +6. Push the branch to your fork. +7. Open a pull request from your fork branch back to the main SimpleChat repository's `Development` branch. + +Do not open contributor pull requests directly to `Staging` or `main`. The repository uses a staged promotion flow: `Development` -> `Staging` -> `main`. +Use the branch names exactly as written here. In this repository, `Development` and `Staging` are capitalized. +After a contribution is merged into `Development`, the SimpleChat team handles promotion forward. + + + +## Suggested Git Commands + +Use whatever Git workflow you prefer, but this is the expected starting point: + +```bash +git clone +cd simplechat +git remote add upstream +git fetch upstream +git switch -c feature/my-change upstream/Development +``` + +When you are ready to publish your work: + +```bash +git push -u origin feature/my-change +``` + +If your branch falls behind, sync it from `upstream/Development` before opening or updating the pull request. + +## Local Development + +Before contributing, make sure you can run SimpleChat locally. + +Recommended local setup in VS Code uses a repo-local `.venv` with Python 3.12. + +From the repo root in PowerShell: + +```powershell +py -3.12 -m venv .venv +.\.venv\Scripts\Activate.ps1 +pip install --upgrade pip +pip install -r application/single_app/requirements.txt +Set-Location application/single_app +$env:FLASK_DEBUG = "1" +python app.py +``` + +For the full local workflow, environment guidance, and notes about Docker, WSL2, and Gunicorn validation, see: + +- [README.md](./README.md) +- [docs/setup_instructions_manual.md](./docs/setup_instructions_manual.md) +- [docs/explanation/running_simplechat_locally.md](./docs/explanation/running_simplechat_locally.md) + +## Pull Request Expectations + +Keep pull requests focused and easy to review. + +- Base your work on `Development`, not `main`. +- Keep unrelated refactors out of the same pull request. +- Explain what changed, why it changed, and how you tested it. +- Include screenshots or short recordings for UI changes when helpful. +- Call out any configuration, schema, security, or deployment impact. +- Update documentation when user-facing behavior or setup steps change. + +## Tests and Validation + +Before opening a pull request, run the tests that match your change. + +- Add or update functional tests for bug fixes and new features when appropriate. +- Run relevant tests from `functional_tests/` and `ui_tests/` when your change affects those areas. +- If you change Flask routes, keep the existing Swagger route decorator pattern intact. + +Pull requests are reviewed by the SimpleChat team and go through repository validation. Depending on the files changed, that can include Python syntax checks, release-note validation, Swagger route validation, and additional maintainer review. Maintainers may also run additional security or AI-assisted review before merge. + +## Security and Repo Conventions + +- Never commit secrets, keys, or environment-specific credentials. +- Review [SECURITY.md](./SECURITY.md) before submitting security-sensitive changes. +- Follow the repository's existing structure and conventions instead of introducing broad cleanup changes. +- If you use AI-assisted tooling while contributing, also review [CLAUDE.md](./CLAUDE.md) and [.github/copilot-instructions.md](./.github/copilot-instructions.md) for repo-specific guidance. + +## Need Help? + +If you are unsure about the right target branch or how to structure a change, open a draft pull request against `Development` and explain the question in the description. That gives the maintainers a concrete starting point for feedback. diff --git a/README.md b/README.md index 8e8f4599..37aa452a 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,10 @@ The application utilizes **Azure Cosmos DB** for storing conversations, metadata [Simple Chat Documentation | Simple Chat Documentation](https://microsoft.github.io/simplechat/) +## Contributing + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for the fork-based workflow, target branch guidance, and local development references for SimpleChat contributors. + ## Quick Deploy [Detailed deployment Guide](./deployers/bicep/README.md) diff --git a/docs/_config.yml b/docs/_config.yml index 5435bf62..9b9ce23c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -55,6 +55,9 @@ navigation: - title: Getting Started url: /setup_instructions/ icon: bi bi-rocket-takeoff + - title: Contributing + url: /contributing/ + icon: bi bi-git - title: Features url: /features/ icon: bi bi-stars diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..c9fa1b28 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,110 @@ +--- +layout: page +title: "Contributing" +description: "How developers should contribute to Simple Chat" +section: "Overview" +permalink: /contributing/ +--- + +# Contributing to Simple Chat + +This page mirrors the repository root contribution guide and should stay aligned with the root `CONTRIBUTING.md` file. + +## Contribution Flow + +SimpleChat contributions should be made through a fork-based workflow. + +1. Fork the repository. +2. Clone your fork locally. +3. Add the main SimpleChat repository as `upstream`. +4. Create a new branch from the upstream `Development` branch. +5. Make your changes in that new branch. +6. Push the branch to your fork. +7. Open a pull request from your fork branch back to the main SimpleChat repository's `Development` branch. + +Do not open contributor pull requests directly to `Staging` or `main`. The repository uses a staged promotion flow: `Development` -> `Staging` -> `main`. +Use the branch names exactly as written here. In this repository, `Development` and `Staging` are capitalized. +After a contribution is merged into `Development`, the SimpleChat team handles promotion forward. + + + +## Suggested Git Commands + +Use whatever Git workflow you prefer, but this is the expected starting point: + +```bash +git clone +cd simplechat +git remote add upstream +git fetch upstream +git switch -c feature/my-change upstream/Development +``` + +When you are ready to publish your work: + +```bash +git push -u origin feature/my-change +``` + +If your branch falls behind, sync it from `upstream/Development` before opening or updating the pull request. + +## Local Development + +Before contributing, make sure you can run SimpleChat locally. + +Recommended local setup in VS Code uses a repo-local `.venv` with Python 3.12. + +From the repo root in PowerShell: + +```powershell +py -3.12 -m venv .venv +.\.venv\Scripts\Activate.ps1 +pip install --upgrade pip +pip install -r application/single_app/requirements.txt +Set-Location application/single_app +$env:FLASK_DEBUG = "1" +python app.py +``` + +For the full local workflow, environment guidance, and notes about Docker, WSL2, and Gunicorn validation, see: + +- [Setup Instructions](./setup_instructions.md) +- [Manual Setup](./setup_instructions_manual.md) +- [Running Simple Chat Locally](./explanation/running_simplechat_locally.md) + +## Pull Request Expectations + +Keep pull requests focused and easy to review. + +- Base your work on `Development`, not `main`. +- Keep unrelated refactors out of the same pull request. +- Explain what changed, why it changed, and how you tested it. +- Include screenshots or short recordings for UI changes when helpful. +- Call out any configuration, schema, security, or deployment impact. +- Update documentation when user-facing behavior or setup steps change. + +## Tests and Validation + +Before opening a pull request, run the tests that match your change. + +- Add or update functional tests for bug fixes and new features when appropriate. +- Run relevant tests from `functional_tests/` and `ui_tests/` when your change affects those areas. +- If you change Flask routes, keep the existing Swagger route decorator pattern intact. + +Pull requests are reviewed by the SimpleChat team and go through repository validation. Depending on the files changed, that can include Python syntax checks, release-note validation, Swagger route validation, and additional maintainer review. Maintainers may also run additional security or AI-assisted review before merge. + +## Security and Repo Conventions + +- Never commit secrets, keys, or environment-specific credentials. +- Review the repository [SECURITY.md](https://github.com/microsoft/simplechat/blob/main/SECURITY.md) before submitting security-sensitive changes. +- Follow the repository's existing structure and conventions instead of introducing broad cleanup changes. +- If you use AI-assisted tooling while contributing, also review the repository guidance in [CLAUDE.md](https://github.com/microsoft/simplechat/blob/main/CLAUDE.md) and [.github/copilot-instructions.md](https://github.com/microsoft/simplechat/blob/main/.github/copilot-instructions.md). + +## Need Help? + +If you are unsure about the right target branch or how to structure a change, open a draft pull request against `Development` and explain the question in the description. That gives the maintainers a concrete starting point for feedback. diff --git a/docs/index.md b/docs/index.md index 502ef358..8cea0212 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,6 +10,10 @@ Built with modularity in mind, the application offers a suite of powerful **opti The application utilizes **Azure Cosmos DB** for storing conversations, metadata, and settings, and is secured using **Azure Active Directory (Entra ID)** for authentication and fine-grained Role-Based Access Control (RBAC) via App Roles. Designed for enterprise use, it runs reliably on **Azure App Service** and supports deployment in both **Azure Commercial** and **Azure Government** cloud environments, offering a versatile tool for knowledge discovery, content generation, and collaborative AI-powered tasks within a secure, customizable, and Azure-native framework. +## Contributing + +If you want to contribute code, documentation, or fixes to Simple Chat, see the [Contributing guide](./contributing.md) for the fork workflow, target branch guidance, pull request expectations, and local development references. + ## Features - **Chat with AI**: Interact with an AI model based on Azure OpenAI’s GPT and Thinking models. From 1f19b3b4ecbb3d2ccfff30a7044583d2a5d21413 Mon Sep 17 00:00:00 2001 From: Paul Lizer Date: Fri, 10 Apr 2026 06:23:38 -0400 Subject: [PATCH 2/2] bumped versions --- application/external_apps/bulkloader/requirements.txt | 2 +- application/external_apps/databaseseeder/requirements.txt | 2 +- docs/Gemfile | 3 +++ docs/Gemfile.lock | 5 +++-- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/application/external_apps/bulkloader/requirements.txt b/application/external_apps/bulkloader/requirements.txt index 2cee8a3b..f8a4a0b0 100644 --- a/application/external_apps/bulkloader/requirements.txt +++ b/application/external_apps/bulkloader/requirements.txt @@ -1,3 +1,3 @@ -requests==2.32.4 +requests==2.33.0 msal==1.31.0 python-dotenv==0.21.0 \ No newline at end of file diff --git a/application/external_apps/databaseseeder/requirements.txt b/application/external_apps/databaseseeder/requirements.txt index dfdf02ed..b0d23371 100644 --- a/application/external_apps/databaseseeder/requirements.txt +++ b/application/external_apps/databaseseeder/requirements.txt @@ -1,3 +1,3 @@ -requests==2.32.4 +requests==2.33.0 msal==1.31.0 python-dotenv==0.21.0 diff --git a/docs/Gemfile b/docs/Gemfile index 478cf7f3..5ba092f7 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -7,6 +7,9 @@ gem "github-pages", group: :jekyll_plugins gem "webrick", "~> 1.8" gem "json", ">= 2.19.2" +# Security override for transitive GitHub Pages/Jekyll dependency +gem "addressable", ">= 2.9.0" + # Jekyll plugins for enhanced functionality group :jekyll_plugins do gem "jekyll-feed" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 3eec6aff..a2371070 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -14,8 +14,8 @@ GEM securerandom (>= 0.3) tzinfo (~> 2.0, >= 2.0.5) uri (>= 0.13.1) - addressable (2.8.7) - public_suffix (>= 2.0.2, < 7.0) + addressable (2.9.0) + public_suffix (>= 2.0.2, < 8.0) base64 (0.3.0) benchmark (0.4.1) bigdecimal (3.2.3) @@ -278,6 +278,7 @@ PLATFORMS x64-mingw-ucrt DEPENDENCIES + addressable (>= 2.9.0) github-pages jekyll-feed jekyll-livereload