Development

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.
+
+<!-- Optional image placeholder:
+Add a branch-flow diagram here later if you want a visual version of the process.
+
+Example:
+![SimpleChat contribution flow](docs/images/contribution-flow.png)
+-->
+
+## Suggested Git Commands
+
+Use whatever Git workflow you prefer, but this is the expected starting point:
+
+```bash
+git clone <your-fork-url>
+cd simplechat
+git remote add upstream <simplechat-upstream-url>
+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.

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)

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

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

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"

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

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

docs/_layouts/latest-release-feature.html

@@ -96,5 +96,5 @@ <h5 class="modal-title mb-1" id="latestFeatureImageModalLabel">Latest Feature Pr
 </article>
 
 {% if feature_meta.images and feature_meta.images.size > 0 %}
-<script src="{{ '/assets/js/latest-release.js' | relative_url }}"></script>
+<script src="{{ '/assets/js/latest-release.js' | relative_url }}?v={{ site.time | date: '%s' }}"></script>
 {% endif %}

docs/_layouts/showcase-page.html

@@ -0,0 +1,122 @@
+---
+layout: default
+---
+
+{% assign accent = page.accent | default: 'blue' %}
+
+<article class="page-content latest-release-page docs-showcase-page latest-release-accent--{{ accent }}">
+  <section class="latest-release-hero">
+    <div class="latest-release-hero-copy">
+      {% if page.breadcrumb and page.breadcrumb.url and page.breadcrumb.label %}
+        <div class="latest-release-breadcrumb">
+          <a href="{{ page.breadcrumb.url | relative_url }}"><i class="bi bi-arrow-left"></i> {{ page.breadcrumb.label }}</a>
+        </div>
+      {% endif %}
+
+      {% if page.eyebrow or page.hero_version %}
+        <div class="latest-release-pill-row">
+          {% if page.eyebrow %}
+            <span class="latest-release-pill">{{ page.eyebrow }}</span>
+          {% endif %}
+          {% if page.hero_version %}
+            <span class="latest-release-subtle">{{ page.hero_version }}</span>
+          {% endif %}
+        </div>
+      {% endif %}
+
+      <h1 class="latest-release-hero-title">{{ page.title }}</h1>
+
+      {% if page.description %}
+        <p class="latest-release-hero-description">{{ page.description }}</p>
+      {% endif %}
+
+      {% if page.hero_pills %}
+        <div class="latest-release-pill-row">
+          {% for pill in page.hero_pills %}
+            <span class="latest-release-pill">{{ pill }}</span>
+          {% endfor %}
+        </div>
+      {% endif %}
+
+      {% if page.hero_links %}
+        <div class="latest-release-hero-actions">
+          {% for link in page.hero_links %}
+            {% assign button_class = 'btn-outline-secondary' %}
+            {% if link.style == 'primary' %}
+              {% assign button_class = 'btn-primary' %}
+            {% elsif link.style == 'secondary' %}
+              {% assign button_class = 'btn-secondary' %}
+            {% endif %}
+            <a href="{{ link.url | relative_url }}" class="btn {{ button_class }} btn-sm">{{ link.label }}</a>
+          {% endfor %}
+        </div>
+      {% endif %}
+    </div>
+
+    <div class="latest-release-hero-art" aria-hidden="true">
+      {% if page.hero_icons and page.hero_icons.size > 1 %}
+        <div class="latest-release-hero-stack">
+          {% for icon in page.hero_icons limit: 3 %}
+            <span><i class="bi {{ icon }}"></i></span>
+          {% endfor %}
+        </div>
+      {% else %}
+        {% assign hero_icon = page.hero_icon %}
+        {% if hero_icon == nil and page.hero_icons and page.hero_icons.size > 0 %}
+          {% assign hero_icon = page.hero_icons[0] %}
+        {% endif %}
+        <div class="latest-release-icon-orb">
+          <i class="bi {{ hero_icon | default: 'bi-stars' }}"></i>
+        </div>
+      {% endif %}
+    </div>
+  </section>
+
+  <div class="latest-release-feature-content">
+    <div class="latest-release-rich-content">
+      {{ content }}
+    </div>
+
+    {% if page.show_nav and page.nav_links %}
+      <nav class="page-navigation mt-5">
+        <div class="row">
+          {% if page.nav_links.prev %}
+            <div class="col-md-6">
+              <a href="{{ page.nav_links.prev.url | relative_url }}" class="btn btn-outline-primary">
+                <i class="bi bi-arrow-left me-2"></i>{{ page.nav_links.prev.title }}
+              </a>
+            </div>
+          {% endif %}
+          {% if page.nav_links.next %}
+            <div class="col-md-6 text-end">
+              <a href="{{ page.nav_links.next.url | relative_url }}" class="btn btn-outline-primary">
+                {{ page.nav_links.next.title }}<i class="bi bi-arrow-right ms-2"></i>
+              </a>
+            </div>
+          {% endif %}
+        </div>
+      </nav>
+    {% endif %}
+  </div>
+
+  <div class="modal fade latest-feature-image-modal" id="latestFeatureImageModal" tabindex="-1" aria-labelledby="latestFeatureImageModalLabel" aria-hidden="true">
+    <div class="modal-dialog modal-dialog-centered modal-xl">
+      <div class="modal-content">
+        <div class="modal-header">
+          <div>
+            <h5 class="modal-title mb-1" id="latestFeatureImageModalLabel">Image Preview</h5>
+            <small class="latest-feature-image-modal-caption" id="latestFeatureImageModalCaption">Click outside the popup to close it.</small>
+          </div>
+          <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+        </div>
+        <div class="modal-body pt-2">
+          <div class="latest-feature-image-frame">
+            <img id="latestFeatureImageModalImage" src="" alt="Image preview" />
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</article>
+
+<script src="{{ '/assets/js/latest-release.js' | relative_url }}?v={{ site.time | date: '%s' }}"></script>