Skip to content

Commit d712a43

Browse files
tylerlv3tylerlv3
committed
2 parents 0b01613 + 2703760 commit d712a43

2 files changed

Lines changed: 220 additions & 70 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 129 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,134 @@
1-
# Contributing
1+
# Contributing Guide
2+
How to set up code test review and release so contributions meet our Definition of Done
23

3-
## Branching
4-
Use `feature/<short-name>` for work branches
4+
## Code of Conduct
5+
We will work with respect and clarity. No harassment. No abuse. Speak up if something is off.
6+
Report concerns to the rest of the team and the project partner. For private concers use direct email.
57

6-
## Reviews
7-
Open a PR early request review when ready at least one reviewer must approve
8+
## Getting Started
9+
Prereqs
10+
- Git installed
11+
- Python 3.11 or newer
12+
- Node LTS
13+
- A terminal and an editor
814

9-
## Coding Standards
10-
Keep modules small and testable write short docs for any public API
15+
Backend setup
16+
- open a terminal
17+
- cd svc
18+
- python -m venv .venv
19+
- activate the venv
20+
- pip install -r requirements.txt
21+
- copy .env.example to .env
22+
- run python main.py
23+
- open http 127.0.0.1 8000 docs and test GET health
1124

12-
## Commits
13-
Use clear messages in the imperative voice
25+
Frontend setup
26+
- open a new terminal
27+
- cd web
28+
- npm install
29+
- npm run dev
30+
- open the URL that Vite prints
1431

15-
## CI
16-
CI must be green to merge
32+
## Branching and Workflow
33+
We use a light trunk model with short lived feature branches
34+
- default branch is main
35+
- create branches as feature short name or fix short name
36+
- rebase small branches before merge if there are conflicts
37+
- do not force push main
38+
39+
## Issues and Planning
40+
We track all work in GitHub Issues
41+
- write a clear title, and one sentence summary
42+
- add labels, feature, fix, docs, chore
43+
- link to related PRs, and meeting notes
44+
45+
## Commit Messages
46+
Keep messages short and clear
47+
- describe what you changed, and why it matters
48+
- one focused change per commit, when possible
49+
50+
- keep each commit focused on one change
51+
## Code Style, Linting, and Formatting
52+
Python
53+
- follow PEP 8 style
54+
- keep functions short and clear
55+
- use type hints for public functions
56+
- run tests before pushing
57+
58+
Web
59+
- use TypeScript types, avoid any
60+
- keep components small and simple
61+
- never include secrets in code
62+
63+
## Testing
64+
Required tests
65+
- service
66+
- update or add tests for any code change
67+
- test both normal use and one error case
68+
- web
69+
- do a quick manual check for now
70+
- add unit tests later when the UI is stable
71+
72+
How to run
73+
- svc pytest -q
74+
- web run the app and make sure it runs properly
75+
76+
## Pull Requests and Reviews
77+
Before you open a PR
78+
- branch is up to date with main
79+
- code runs locally
80+
- tests pass locally
81+
- update docs if the user sees a change
82+
83+
PR requirements
84+
- use the PR template in the repo
85+
- small PRs are preferred
86+
- request at least one reviewer who is not the author
87+
88+
Review rules
89+
- at least one approval
90+
- all review comments resolved
91+
- no red CI checks
92+
93+
## CI/CD
94+
Current CI
95+
- file .github workflows ci.yml
96+
- runs on push and pull request and confirms the pipeline is wired
97+
98+
Required before merge
99+
- CI is green
100+
- svc tests pass locally pytest -q
101+
- web builds locally npm run build
102+
103+
We will expand CI to run pytest and a web type check. Until then reviewers must run these locally.
104+
105+
## Security and Secrets
106+
- never commit secrets or API keys
107+
- do not paste keys in issues or PRs
108+
- use .env files that are ignored by git
109+
- report security bugs privately to the lead and partner
110+
- keep dependencies current when possible
111+
112+
Prohibited
113+
- hard coded credentials
114+
- copying key material into sample code
115+
116+
## Documentation Expectations
117+
Update docs when something changes
118+
- update README for setup or usage changes
119+
- update quick start guide for researchers
120+
- add short docstrings for important functions
121+
- note visible changes in the PR description
122+
123+
## Release Process
124+
We make tags when needed
125+
- tag format: v0.minor.patch
126+
- update README if needed
127+
- add a short summary of changes in the PR
128+
- to undo a release, revert the merge commit
129+
130+
## Support and Contact
131+
Need help?
132+
- ask in the team Discord first
133+
- if stuck for more than a day, post in the issue and tag the lead
134+
- for project questions, contact Dr. Pierson or Alex

‎DEV-SETUP.md‎

Lines changed: 91 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,119 @@
1-
2-
## What you need to install
3-
**Git** – Get it from [https://git-scm.com](https://git-scm.com)
4-
Check installation:
5-
git --version
6-
7-
8-
**Python 3.11 or newer** – Get it from [https://python.org](https://python.org)
9-
On Windows, check “Add Python to PATH”.
10-
Check installation:
11-
python --version
12-
13-
14-
**Node.js (LTS) and NPM** – Get it from [https://nodejs.org](https://nodejs.org)
15-
Check installation:
16-
node --version
17-
npm --version
1+
# What you need to install
2+
3+
1. `Git`
4+
Get it from `https://git-scm.com`
5+
Check installation
6+
```bash
7+
git --version
8+
```
9+
10+
2. `Python 3.11 or newer`
11+
Get it from `https://python.org`
12+
On Windows check `Add Python to PATH`
13+
Check installation
14+
```bash
15+
python --version
16+
```
17+
18+
3. `Node.js (LTS) and NPM`
19+
Get it from `https://nodejs.org`
20+
Check installation
21+
```bash
22+
node --version
23+
npm --version
24+
```
1825

1926
---
2027

21-
## Repository setup
22-
Clone the repository and go inside
23-
cd GlazingControlApp
28+
# Repository setup
29+
30+
1. Clone the repository and go inside
31+
```bash
32+
cd GlazingControlApp
33+
```
2434

2535
---
2636

27-
## Run the service
28-
Open a terminal in the `svc` folder:
29-
cd svc
37+
# Run the service
3038

39+
1. Open a terminal in the `svc` folder
40+
```bash
41+
cd svc
42+
```
3143

32-
Create and activate a virtual environment:
33-
- **Windows PowerShell**
34-
python -m venv .venv
35-
..venv\Scripts\Activate.ps1
44+
2. Create and activate a virtual environment
3645

37-
- **Windows CMD**
38-
.venv\Scripts\activate
39-
40-
- **Mac/Linux**
41-
python3 -m venv .venv
42-
source .venv/bin/activate
46+
2.1 Windows PowerShell
47+
```powershell
48+
python -m venv .venv
49+
.venv\Scripts\Activate.ps1
50+
```
4351

52+
2.2 Windows CMD
53+
```cmd
54+
.venv\Scripts\activate
55+
```
4456

45-
Install packages:
46-
pip install --upgrade pip
47-
pip install -r requirements.txt
57+
2.3 Mac Linux
58+
```bash
59+
python3 -m venv .venv
60+
source .venv/bin/activate
61+
```
4862

63+
3. Install packages
64+
```bash
65+
pip install --upgrade pip
66+
pip install -r requirements.txt
67+
```
4968

50-
Create your `.env` file from the example:
51-
- **Windows**
52-
copy .env.example .env
69+
4. Create your `.env` file from the example
5370

54-
- **Mac/Linux**
55-
cp .env.example .env
71+
4.1 Windows
72+
```cmd
73+
copy .env.example .env
74+
```
5675

76+
4.2 Mac Linux
77+
```bash
78+
cp .env.example .env
79+
```
5780

58-
Start the server:
59-
python main.py
81+
5. Start the server
82+
```bash
83+
python main.py
84+
```
6085

61-
You should see Uvicorn running on port 8000.
86+
You should see Uvicorn running on port 8000
6287

63-
Open the API docs in a browser: http://127.0.0.1:8000/docs
88+
Open the API docs in a browser at `http://127.0.0.1:8000/docs`
6489

6590
---
6691

67-
## Run the web app
68-
Open a new terminal in the `web` folder:
69-
cd web
92+
# Run the web app
7093

94+
1. Open a new terminal in the `web` folder
95+
```bash
96+
cd web
97+
```
7198

72-
Install packages:
73-
npm install
99+
2. Install packages
100+
```bash
101+
npm install
102+
```
74103

104+
3. Start the dev server
105+
```bash
106+
npm run dev
107+
```
75108

76-
Start the dev server:
77-
npm run dev
109+
Open the link shown by Vite usually `http://127.0.0.1:5173`
110+
You should see the control interface
78111

112+
---
79113

80-
Open the link shown by Vite (usually http://127.0.0.1:5173).
81-
You should see the control interface.
114+
# Use the app
82115

83-
Use the app:
84-
- The header shows service status
85-
- Pick a group, set a level, press **Set group**
86-
- Move a slider on any panel and press **Apply**
87-
- Press **Refresh** in the header to reload state
116+
1. The header shows service status
117+
2. Pick a group set a level press `Set group`
118+
3. Move a slider on any panel and press `Apply`
119+
4. Press `Refresh` in the header to reload state

0 commit comments

Comments
 (0)