From aa9865f5d05b771c09462ddc422fd43f4b437f1d Mon Sep 17 00:00:00 2001 From: rafa-ruiz Date: Tue, 3 Mar 2026 13:19:42 -0800 Subject: [PATCH] docs: add contribution standards, PR template and env vars policy --- .github/pull_request_template.md | 76 +++++++++++ CONTRIBUTING.md | 228 +++++++++++++++++++++++++++++++ README.md | 43 ++++-- changelog | 16 ++- 4 files changed, 347 insertions(+), 16 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..f03cd48 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,76 @@ +## Summary + + + +## Type of change + +- [ ] New feature (`Added`) +- [ ] Change to existing behavior (`Changed`) +- [ ] Bug fix (`Fixed`) +- [ ] Security / infrastructure (`Security`) +- [ ] Internal refactor (no behavioral change) +- [ ] Docs / changelog only + +--- + +## PR Checklist + +> All applicable items must be checked before requesting review. +> Reviewers are authorized to close and request resubmission of PRs that do not meet these standards. + +### Code & Environment +- [ ] Tested locally against the **authorized Devaron Cluster** (no external or unauthorized infrastructure used) +- [ ] No personal IDE/environment files committed (`.vscode`, `.devcontainer`, etc.) +- [ ] No `root` user configurations introduced +- [ ] `Dockerfile` and `.dockerignore` comply with build context standards (`/app` only, no `/workspace`) + +### Ingestion Files +- [ ] **No ingestion files were added or modified in this PR** +- [ ] **Ingestion files were added or modified** and are committed to the repository under `ingestion/` or `data/` + +### Environment Variables +- [ ] **No new environment variables were introduced in this PR** +- [ ] **New variables were introduced** and are fully documented in the `.env` table in `README.md` + +If new variables were added, list them here: + +| Variable | Required | Description | Example value | +|---|---|---|---| +| `VARIABLE_NAME` | Yes / No | What it does | `example` | + +### Changelog +- [ ] **Not required** — internal refactor, typo/comment fix, or zero behavioral impact +- [ ] **Updated** — entry added to `changelog` with correct version bump and today's date + +### Documentation +- [ ] **Not required** — internal change with no impact on setup, API, or usage +- [ ] **Updated** — `README.md` or relevant docs reflect this change + +--- + +## Changelog entry + + + +``` +## [X.Y.Z] - YYYY-MM-DD + +### Added / Changed / Fixed / Security +- LABEL: Description. +``` + +--- + +## Infrastructure status during testing + +| Tunnel | Status | +|---|---| +| Ollama (port 11434) | `active` / `N/A` | +| Elasticsearch (port 9200) | `active` / `N/A` | +| PostgreSQL (port 5432) | `active` / `N/A` | + +--- + +## Notes for reviewer + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e106c98 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,228 @@ +# Contributing to Brunix Assistance Engine + +> This document is the single source of truth for all contribution standards in the Brunix Assistance Engine repository. All contributors — regardless of seniority or role — are expected to read, understand, and comply with these guidelines before opening any Pull Request. + +--- + +## Table of Contents + +1. [Development Workflow (GitFlow)](#1-development-workflow-gitflow) +2. [Infrastructure Standards](#2-infrastructure-standards) +3. [Repository Standards](#3-repository-standards) +4. [Pull Request Requirements](#4-pull-request-requirements) +5. [Ingestion Files Policy](#5-ingestion-files-policy) +6. [Environment Variables Policy](#6-environment-variables-policy) +7. [Changelog Policy](#7-changelog-policy) +8. [Documentation Policy](#8-documentation-policy) +9. [Incident & Blockage Reporting](#9-incident--blockage-reporting) + +--- + +## 1. Development Workflow (GitFlow) + +### Branch Strategy + +| Branch type | Naming convention | Purpose | +|---|---|---| +| Feature | `*-dev` | Active development — volatile, no CI validation | +| Main | `main` | Production-ready, fully validated | + +- **Feature branches** (`*-dev`) are volatile environments. No validation tests or infrastructure deployments are performed on these branches. +- **Official validation** only occurs after a documented Pull Request is merged into `main`. +- **Developer responsibility:** Code must be stable and functional against the authorized environment before a PR is opened. Do not use the PR review process as a debugging step. + +--- + +## 2. Infrastructure Standards + +The project provides a validated, shared environment (Devaron Cluster, Vultr) including Ollama, Elasticsearch, and PostgreSQL. + +- **Authorized environment only.** The use of parallel, unauthorized infrastructures — external EC2 instances, ad-hoc local setups, non-replicable environments — is strictly prohibited for official development. +- **No siloed environments.** Isolated development creates technical debt and incompatibility risks that directly impact delivery timelines. +- All infrastructure access must be established via the documented `kubectl` port-forward tunnels defined in the [README](./README.md#3-infrastructure-tunnels). + +--- + +## 3. Repository Standards + +### IDE Agnosticism + +The `main` branch must remain neutral to any individual's development environment. The following **must not** be committed under any circumstance: + +- `.devcontainer/` +- `.vscode/` +- Any local IDE or editor configuration files + +The `.gitignore` automates exclusion of these artifacts. Ensure your local environment is fully decoupled from the production-ready source code. + +### Security & Least Privilege + +- Never use `root` as `remoteUser` in any shared dev environment configuration. +- All configurations must comply with the **Principle of Least Privilege**. +- Using root in shared environments introduces unacceptable supply chain risk. + +### Docker & Build Context + +- All executable code must reside in `/app` within the container. +- The `/workspace` root directory is **deprecated** — do not reference it. +- Every PR must verify the `Dockerfile` context is optimized via `.dockerignore`. + +> **PRs that violate these architectural standards will be rejected without review.** + +--- + +## 4. Pull Request Requirements + +A PR is not ready for review unless **all applicable items** in the following checklist are satisfied. Reviewers are authorized to close PRs that do not meet these standards and request resubmission. + +### PR Checklist + +**Code & Environment** +- [ ] Tested locally against the authorized Devaron Cluster (no unauthorized infrastructure used) +- [ ] No IDE or environment configuration files committed (`.vscode`, `.devcontainer`, etc.) +- [ ] No `root` user configurations introduced +- [ ] `Dockerfile` and `.dockerignore` comply with build context standards + +**Ingestion Files** *(see [Section 5](#5-ingestion-files-policy))* +- [ ] No ingestion files were added or modified +- [ ] New or modified ingestion files are committed to the repository under `ingestion/` or `data/` + +**Environment Variables** *(see [Section 6](#6-environment-variables-policy))* +- [ ] No new environment variables were introduced +- [ ] New environment variables are documented in the `.env` reference table in `README.md` + +**Changelog** *(see [Section 6](#6-changelog-policy))* +- [ ] No changelog entry required (internal refactor, comment/typo fix, zero behavioral change) +- [ ] Changelog updated with correct version bump and date + +**Documentation** *(see [Section 7](#7-documentation-policy))* +- [ ] No documentation update required (internal change, no impact on setup or API) +- [ ] `README.md` or relevant docs updated to reflect this change + +--- + +## 5. Ingestion Files Policy + +All files used to populate the vector knowledge base — source documents, AVAP manuals, structured data, or ingestion scripts — **must be committed to the repository.** + +### Rules + +- Ingestion files must reside in a dedicated directory (e.g., `ingestion/` or `data/`) within the repository. +- Any PR that introduces new knowledge base content or modifies existing ingestion pipelines must include the corresponding source files. +- Files containing sensitive content that cannot be committed in plain form must be flagged for discussion before proceeding. Encryption, redaction, or a separate private submodule are all valid solutions — committing to an external or local-only location is not. + +### Why this matters + +The Elasticsearch vector index is only as reliable as the source material that feeds it. Ingestion files that exist only on a local machine or external location cannot be audited, rebuilt, or validated by the team. A knowledge base populated from untracked files is a non-reproducible dependency — and a risk to the entire RAG pipeline. + +--- + +## 6. Environment Variables Policy + +This is a critical requirement. **Every environment variable introduced in a PR must be documented before the PR can be merged.** + +### Rules + +- Any new variable added to the codebase (`.env`, `docker-compose.yaml`, `server.py`, or any config file) must be declared in the `.env` reference table in `README.md`. +- The documentation must include: variable name, purpose, whether it is required or optional, and an example value. +- Variables that contain secrets must use placeholder values (e.g., `your-secret-key-here`) — never commit real values. + +### Required format in README.md + +```markdown +| Variable | Required | Description | Example | +|---|---|---|---| +| `LANGFUSE_PUBLIC_KEY` | Yes | Langfuse project public key for tracing | `pk-lf-...` | +| `LANGFUSE_SECRET_KEY` | Yes | Langfuse project secret key | `sk-lf-...` | +| `LANGFUSE_HOST` | Yes | Langfuse server endpoint | `http://45.77.119.180` | +| `NEW_VARIABLE` | Yes | Description of what it does | `example-value` | +``` + +### Why this matters + +An undocumented environment variable silently breaks the setup for every other developer on the team. It also makes the service non-reproducible, which is a direct violation of the infrastructure standards in Section 2. There are no exceptions to this policy. + +--- + +## 7. Changelog Policy + +The `changelog` file tracks all notable changes and follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +### When a changelog entry IS required + +| Change type | Label to use | +|---|---| +| New feature or capability | `Added` | +| Change to existing behavior, API, or interface | `Changed` | +| Bug fix | `Fixed` | +| Security patch or security-related change | `Security` | +| Breaking change or deprecation | `Deprecated` / `Removed` | + +### When a changelog entry is NOT required + +- Typo or comment fixes only +- Internal refactors with zero behavioral or interface change +- Tooling/CI updates with no user-visible impact + +**If in doubt, add an entry.** + +### Format + +New entries go at the top of the file, above the previous version: + +``` +## [X.Y.Z] - YYYY-MM-DD + +### Added +- LABEL: Description of the new feature or capability. + +### Changed +- LABEL: Description of what changed and the rationale. + +### Fixed +- LABEL: Description of the bug resolved. +``` + +Use uppercase short labels for scanability: `API:`, `DOCKER:`, `INFRA:`, `SECURITY:`, `ENV:`, `CONFIG:`. + +--- + +## 8. Documentation Policy + +### When documentation MUST be updated + +Update `README.md` (or the relevant doc file) if the PR includes any of the following: + +- Changes to project structure (new files, directories, removed components) +- Changes to setup, installation, or environment configuration +- New or modified API endpoints or Protobuf definitions (`brunix.proto`) +- New, modified, or removed environment variables +- Changes to infrastructure tunnels or Kubernetes service names +- New dependencies or updated dependency versions +- Changes to security, access, or repository standards + +### When documentation is NOT required + +- Internal implementation changes with no impact on setup, usage, or API +- Fixes that do not alter any documented behavior + +> **PRs that change user-facing behavior or setup without updating documentation will be rejected.** + +--- + +## 9. Incident & Blockage Reporting + +If you encounter a technical blockage (connection timeouts, service downtime, tunnel failures): + +1. **Immediate notification** — Report via the designated Slack channel at the moment of detection. Do not wait until end of day. +2. **GitHub Issue must include:** + - The exact command executed + - Full terminal output (complete error logs) + - Current status of all `kubectl` tunnels +3. **Resolution** — If the error is not reproducible by the CTO/DevOps team, a 5-minute live debugging session will be scheduled to identify local network or configuration issues. + +--- + +*These standards exist to protect the integrity of the Brunix Assistance Engine and to ensure every member of the team can work confidently and efficiently. They are not bureaucratic overhead — they are the foundation of a reliable, scalable engineering practice.* + +*— Rafael Ruiz, CTO, AVAP Technology* diff --git a/README.md b/README.md index 083b1fd..ae52878 100644 --- a/README.md +++ b/README.md @@ -43,14 +43,17 @@ graph TD ```text . -├── Dockerfile # Container definition for the Engine -├── README.md # System documentation & Dev guide -├── changelog # Version tracking and release history -├── docker-compose.yaml # Local orchestration for dev environment +├── .github/ +│ └── pull_request_template.md # Mandatory PR checklist +├── Dockerfile # Container definition for the Engine +├── README.md # System documentation & Dev guide +├── CONTRIBUTING.md # Contribution standards & policies +├── changelog # Version tracking and release history +├── docker-compose.yaml # Local orchestration for dev environment ├── protos/ -│ └── brunix.proto # Protocol Buffers: The source of truth for the API +│ └── brunix.proto # Protocol Buffers: The source of truth for the API └── src/ - └── server.py # Core Logic: gRPC Server & RAG Orchestration + └── server.py # Core Logic: gRPC Server & RAG Orchestration ``` --- @@ -87,8 +90,6 @@ sequenceDiagram Note over E: Close Langfuse Trace ``` - - --- ## Development Setup @@ -102,7 +103,13 @@ sequenceDiagram The engine utilizes Langfuse for end-to-end tracing and performance monitoring. 1. Access the Dashboard: **http://45.77.119.180** 2. Create a project and generate API Keys in **Settings**. -3. Configure your local `.env` file: +3. Configure your local `.env` file using the reference table below. + +### 3. Environment Variables Reference + +> **Policy:** Every environment variable used by the engine must be documented in this table. Any PR that introduces a new variable without a corresponding entry here will be rejected. See [CONTRIBUTING.md](./CONTRIBUTING.md#5-environment-variables-policy) for full details. + +Create a `.env` file in the project root with the following variables: ```env LANGFUSE_PUBLIC_KEY=pk-lf-... @@ -110,7 +117,15 @@ LANGFUSE_SECRET_KEY=sk-lf-... LANGFUSE_HOST=http://45.77.119.180 ``` -### 3. Infrastructure Tunnels +| Variable | Required | Description | Example | +|---|---|---|---| +| `LANGFUSE_PUBLIC_KEY` | Yes | Langfuse project public key for tracing and observability | `pk-lf-...` | +| `LANGFUSE_SECRET_KEY` | Yes | Langfuse project secret key | `sk-lf-...` | +| `LANGFUSE_HOST` | Yes | Langfuse server endpoint (Devaron Cluster) | `http://45.77.119.180` | + +> 🔒 Never commit real secret values. Use placeholder values when sharing configuration examples. + +### 4. Infrastructure Tunnels Open a terminal and establish the connection to the Devaron Cluster: ```bash @@ -124,9 +139,7 @@ kubectl port-forward --address 0.0.0.0 svc/brunix-vector-db 9200:9200 -n brunix kubectl port-forward --address 0.0.0.0 svc/brunix-postgres 5432:5432 -n brunix --kubeconfig ./kubernetes/ivar.yaml & ``` - - -### 4. Launch the Engine +### 5. Launch the Engine ```bash docker-compose up -d --build ``` @@ -167,10 +180,12 @@ To maintain production-grade security and image efficiency, this project enforce *Failure to comply with these architectural standards will result in PR rejection.* +For the full set of contribution standards, see [CONTRIBUTING.md](./CONTRIBUTING.md). + --- ## Security & Intellectual Property * **Data Privacy:** All LLM processing and vector searches are conducted within a private Kubernetes environment. * **Proprietary Technology:** This repository contains the **AVAP Technology** stack (101OBEX) and specialized training logic (MrHouston). Unauthorized distribution is prohibited. ---- \ No newline at end of file +--- diff --git a/changelog b/changelog index 87fa691..8c1e0c6 100644 --- a/changelog +++ b/changelog @@ -4,6 +4,19 @@ All notable changes to the **Brunix Assistance Engine** will be documented in th --- +## [1.2.0] - 2026-03-03 + +### Added +- GOVERNANCE: Introduced `CONTRIBUTING.md` as the single source of truth for all contribution standards, covering GitFlow, infrastructure policy, repository standards, environment variables, changelog, documentation, and incident reporting. +- GOVERNANCE: Added `.github/pull_request_template.md` enforcing a mandatory structured checklist on every PR — including explicit sign-off on environment variables, changelog, and documentation. +- DOCS: Added Environment Variables reference table to `README.md`. All variables must be registered here. PRs introducing undocumented variables will be rejected. +- DOCS: Updated project structure map in `README.md` to reflect new governance files. + +### Changed +- PROCESS: Pull Requests that introduce new environment variables without documentation, omit required changelog entries, or skip required documentation updates are now formally non-mergeable per `CONTRIBUTING.md`. + +--- + ## [1.1.0] - 2026-02-16 ### Added @@ -17,15 +30,14 @@ All notable changes to the **Brunix Assistance Engine** will be documented in th ### Fixed - RESOLVED: Issue where non-production files were being bundled into the Docker image, improving deployment speed and container isolation. +--- ## [1.0.0] - 2026-02-09 ### Added - - **System Architecture:** Implementation of the triple-layer stack (Engine, Vector DB, Observability). - **Core Engine:** Deployment of the `brunix-assistance-engine` using **Python 3.11**, **LangChain**, and **LangGraph** for agentic workflows. - **Communication Layer:** Established **gRPC** as the primary high-performance interface (Port 50051/50052). - **Knowledge Base:** Integration of **Elasticsearch 8.12** (`brunix-vector-db`) for AVAP technology RAG support. - **Observability Framework:** Deployment of **Langfuse** and **PostgreSQL** for full trace audit and cost management. - **Security:** Initial network isolation within Docker (`avap-network`) and production-ready secret management design. -