RafaelRuiz
/
assistance-engine
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add contribution standards, PR template and env vars policy

This commit is contained in:
rafa-ruiz 2026-03-03 13:19:42 -08:00
parent 5024bde8fb
commit aa9865f5d0
4 changed files with 347 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
.github/pull_request_template.md vendored Normal file
View File

@ -0,0 +1,76 @@
## Summary
<!-- What does this PR do? Why is this change needed? Be specific. -->
## 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
<!-- Paste the entry you added, or write "N/A" -->
```
## [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
<!-- Anything the reviewer should pay special attention to. If none, write "None." -->

228
CONTRIBUTING.md Normal file
View File

@ -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*

41
README.md
View File

@ -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,6 +180,8 @@ 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

16
changelog
View File

@ -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.