Skip to content

Commit 32e3278

Browse files
paresh011paresh011
authored
Merge pull request #73 from orekoapp/chore/contributor-experience
chore: improve contributor experience
2 parents 05d7b46 + 3459c2d commit 32e3278

7 files changed

Lines changed: 153 additions & 69 deletions

File tree

‎.env.example‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# ===========================================
2-
# Oreko Environment Variables
2+
# Oreko Environment Variables (root — used by Docker)
33
# ===========================================
4-
# Copy this file to .env.local and fill in the values
4+
# For Next.js development, use apps/web/.env.example instead:
5+
# cp apps/web/.env.example apps/web/.env.local
56

67
# Application
78
NODE_ENV=development

‎.husky/pre-commit‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
lint-staged

‎CONTRIBUTING.md‎

Lines changed: 56 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Oreko is an open-source, self-hosted visual quote and invoice management tool de
2222
By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for everyone. Please be respectful, considerate, and constructive in all interactions.
2323

2424
Key principles:
25+
2526
- Be welcoming and inclusive
2627
- Be respectful of differing viewpoints
2728
- Accept constructive criticism gracefully
@@ -42,31 +43,38 @@ When creating a bug report, please use the following template:
4243

4344
```markdown
4445
## Bug Description
46+
4547
A clear and concise description of what the bug is.
4648

4749
## Steps to Reproduce
50+
4851
1. Go to '...'
4952
2. Click on '...'
5053
3. Scroll down to '...'
5154
4. See error
5255

5356
## Expected Behavior
57+
5458
A clear description of what you expected to happen.
5559

5660
## Actual Behavior
61+
5762
What actually happened instead.
5863

5964
## Screenshots
65+
6066
If applicable, add screenshots to help explain the problem.
6167

6268
## Environment
69+
6370
- OS: [e.g., macOS 14.0, Ubuntu 22.04, Windows 11]
6471
- Browser: [e.g., Chrome 120, Firefox 121]
6572
- Node.js version: [e.g., 20.10.0]
6673
- pnpm version: [e.g., 8.12.0]
6774
- Oreko version/commit: [e.g., v1.0.0 or commit hash]
6875

6976
## Additional Context
77+
7078
Add any other context about the problem here, including error logs from the console or server.
7179
```
7280

@@ -82,24 +90,31 @@ Have an idea for a new feature? We'd love to hear it! Before suggesting a featur
8290

8391
```markdown
8492
## Feature Summary
93+
8594
A brief, one-line description of the feature.
8695

8796
## Problem Statement
97+
8898
What problem does this feature solve? Who would benefit from it?
8999

90100
## Proposed Solution
101+
91102
Describe your proposed solution in detail.
92103

93104
## Alternative Solutions
105+
94106
Have you considered any alternative approaches? What are their pros and cons?
95107

96108
## Additional Context
109+
97110
- Mock-ups or wireframes (if applicable)
98111
- Examples from other applications
99112
- Any technical considerations
100113

101114
## Priority Suggestion
115+
102116
Where do you think this fits?
117+
103118
- [ ] P0 - Critical for MVP
104119
- [ ] P1 - Should have for v1.1
105120
- [ ] P2 - Nice to have for future versions
@@ -113,9 +128,8 @@ Before you begin, ensure you have the following installed:
113128

114129
- Node.js 20+
115130
- pnpm 8+
116-
- Docker and Docker Compose
131+
- Docker and Docker Compose (recommended for PostgreSQL and Mailpit)
117132
- PostgreSQL 15+ (or use Docker)
118-
- Redis 7+ (or use Docker)
119133
- Git
120134

121135
### Getting Started
@@ -141,13 +155,12 @@ pnpm install
141155
#### 3. Set Up Environment
142156

143157
```bash
144-
# Copy the example environment file
158+
# Copy the environment file for the web app
145159
cp apps/web/.env.example apps/web/.env.local
146160

147-
# Edit .env.local with your local configuration
161+
# Edit apps/web/.env.local with your local configuration
148162
# Required variables:
149163
# - DATABASE_URL
150-
# - REDIS_URL
151164
# - NEXTAUTH_SECRET
152165
# - NEXTAUTH_URL
153166
```
@@ -172,14 +185,14 @@ pnpm dev
172185

173186
Use descriptive branch names with the appropriate prefix:
174187

175-
| Prefix | Use Case | Example |
176-
|--------|----------|---------|
177-
| `feature/` | New features | `feature/quote-pdf-export` |
178-
| `fix/` | Bug fixes | `fix/invoice-calculation-error` |
179-
| `chore/` | Maintenance tasks | `chore/update-dependencies` |
180-
| `docs/` | Documentation only | `docs/api-reference` |
181-
| `refactor/` | Code refactoring | `refactor/quote-builder-hooks` |
182-
| `test/` | Test additions/fixes | `test/stripe-integration` |
188+
| Prefix | Use Case | Example |
189+
| ----------- | -------------------- | ------------------------------- |
190+
| `feature/` | New features | `feature/quote-pdf-export` |
191+
| `fix/` | Bug fixes | `fix/invoice-calculation-error` |
192+
| `chore/` | Maintenance tasks | `chore/update-dependencies` |
193+
| `docs/` | Documentation only | `docs/api-reference` |
194+
| `refactor/` | Code refactoring | `refactor/quote-builder-hooks` |
195+
| `test/` | Test additions/fixes | `test/stripe-integration` |
183196

184197
### Creating a Branch
185198

@@ -208,19 +221,19 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/) for clear
208221

209222
#### Types
210223

211-
| Type | Description |
212-
|------|-------------|
213-
| `feat` | A new feature |
214-
| `fix` | A bug fix |
215-
| `docs` | Documentation changes only |
216-
| `style` | Code style changes (formatting, semicolons, etc.) |
224+
| Type | Description |
225+
| ---------- | --------------------------------------------------- |
226+
| `feat` | A new feature |
227+
| `fix` | A bug fix |
228+
| `docs` | Documentation changes only |
229+
| `style` | Code style changes (formatting, semicolons, etc.) |
217230
| `refactor` | Code changes that neither fix bugs nor add features |
218-
| `perf` | Performance improvements |
219-
| `test` | Adding or updating tests |
220-
| `build` | Build system or dependency changes |
221-
| `ci` | CI/CD configuration changes |
222-
| `chore` | Other changes that don't modify src or test files |
223-
| `revert` | Reverts a previous commit |
231+
| `perf` | Performance improvements |
232+
| `test` | Adding or updating tests |
233+
| `build` | Build system or dependency changes |
234+
| `ci` | CI/CD configuration changes |
235+
| `chore` | Other changes that don't modify src or test files |
236+
| `revert` | Reverts a previous commit |
224237

225238
#### Scopes (optional)
226239

@@ -286,13 +299,13 @@ git rebase upstream/main
286299
287300
### Naming Conventions
288301
289-
| Element | Convention | Example |
290-
|---------|------------|---------|
291-
| Components | PascalCase | `QuoteBuilder.tsx` |
292-
| Utilities | camelCase | `formatCurrency.ts` |
293-
| Constants | UPPER_SNAKE_CASE | `API_ENDPOINTS` |
294-
| CSS classes | Tailwind utility-first | `className="flex items-center"` |
295-
| Database tables | snake_case | `quote_line_items` |
302+
| Element | Convention | Example |
303+
| --------------- | ---------------------- | ------------------------------- |
304+
| Components | PascalCase | `QuoteBuilder.tsx` |
305+
| Utilities | camelCase | `formatCurrency.ts` |
306+
| Constants | UPPER_SNAKE_CASE | `API_ENDPOINTS` |
307+
| CSS classes | Tailwind utility-first | `className="flex items-center"` |
308+
| Database tables | snake_case | `quote_line_items` |
296309
297310
### File Organization
298311
@@ -360,11 +373,11 @@ All contributions must include appropriate tests. Our testing strategy:
360373
361374
### Test Types
362375
363-
| Type | Tool | Location | Purpose |
364-
|------|------|----------|---------|
365-
| Unit | Vitest | `*.test.ts` | Utilities, hooks, pure functions |
366-
| Component | React Testing Library | `*.test.tsx` | Component behavior |
367-
| E2E | Playwright | `e2e/*.spec.ts` | Critical user flows |
376+
| Type | Tool | Location | Purpose |
377+
| --------- | --------------------- | --------------- | -------------------------------- |
378+
| Unit | Vitest | `*.test.ts` | Utilities, hooks, pure functions |
379+
| Component | React Testing Library | `*.test.tsx` | Component behavior |
380+
| E2E | Playwright | `e2e/*.spec.ts` | Critical user flows |
368381
369382
### Running Tests
370383
@@ -444,19 +457,23 @@ describe('calculateQuoteTotal', () => {
444457
445458
```markdown
446459
## Description
460+
447461
Brief description of changes and motivation.
448462
449463
## Type of Change
464+
450465
- [ ] Bug fix (non-breaking change that fixes an issue)
451466
- [ ] New feature (non-breaking change that adds functionality)
452467
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
453468
- [ ] Documentation update
454469
- [ ] Refactoring (no functional changes)
455470
456471
## Related Issues
472+
457473
Fixes #(issue number)
458474
459475
## How Has This Been Tested?
476+
460477
Describe the tests you ran to verify your changes.
461478
462479
- [ ] Unit tests
@@ -465,9 +482,11 @@ Describe the tests you ran to verify your changes.
465482
- [ ] Manual testing
466483
467484
## Screenshots (if applicable)
485+
468486
Add screenshots for UI changes.
469487
470488
## Checklist
489+
471490
- [ ] My code follows the project's style guidelines
472491
- [ ] I have performed a self-review of my code
473492
- [ ] I have commented my code where necessary
@@ -583,4 +602,3 @@ pnpm db:studio # Open Prisma Studio
583602
---
584603
585604
Thank you for contributing to Oreko! Your efforts help make quote and invoice management better for small businesses everywhere.
586-

‎README.md‎

Lines changed: 29 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
<br />
2525

2626
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
27+
[![CI](https://github.com/orekoapp/oreko/actions/workflows/ci.yml/badge.svg)](https://github.com/orekoapp/oreko/actions/workflows/ci.yml)
2728
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
2829
[![Next.js](https://img.shields.io/badge/Next.js-14+-black.svg)](https://nextjs.org/)
2930

@@ -39,10 +40,10 @@
3940

4041
## What You Can Do With Oreko
4142

42-
+ [Visual Quote Builder](#visual-quote-builder)
43-
+ [Invoicing with one-click conversion](#invoicing-with-one-click-conversion)
44-
+ [Client Management](#client-management)
45-
+ [Contracts, payments, and analytics](#contracts-payments-and-analytics)
43+
- [Visual Quote Builder](#visual-quote-builder)
44+
- [Invoicing with one-click conversion](#invoicing-with-one-click-conversion)
45+
- [Client Management](#client-management)
46+
- [Contracts, payments, and analytics](#contracts-payments-and-analytics)
4647

4748
### Visual Quote Builder
4849

@@ -70,42 +71,47 @@ Centralized client database with full history, lifetime value tracking, and cont
7071

7172
### Contracts, payments, and analytics
7273

73-
| Feature | Description |
74-
| ------------------------------ | -------------------------------------------------------------------------- |
75-
| **E-Signature Capture** | Legally compliant electronic signatures (E-SIGN, UETA) |
76-
| **Stripe Payment Integration** | Accept credit cards and ACH payments via Stripe Connect |
77-
| **PDF Generation** | Professional PDF exports for quotes and invoices |
78-
| **Email Notifications** | Automated email workflows for quotes, invoices, and reminders |
74+
| Feature | Description |
75+
| ------------------------------ | --------------------------------------------------------------------------- |
76+
| **E-Signature Capture** | Legally compliant electronic signatures (E-SIGN, UETA) |
77+
| **Stripe Payment Integration** | Accept credit cards and ACH payments via Stripe Connect |
78+
| **PDF Generation** | Professional PDF exports for quotes and invoices |
79+
| **Email Notifications** | Automated email workflows for quotes, invoices, and reminders |
7980
| **Dashboard Analytics** | Revenue trends, quote conversion rates, invoice status, and client insights |
80-
| **Contract Templates** | Draft contracts from templates, send for e-signature |
81-
| **Rate Card System** | Predefined services and pricing tiers for quick quoting |
82-
| **Milestone Payments** | Support for deposits, milestones, and recurring payments |
83-
| **Modular Workspace** | Enable only the modules you need |
84-
| **Self-Hosted** | Full control over your data with Docker deployment |
81+
| **Contract Templates** | Draft contracts from templates, send for e-signature |
82+
| **Rate Card System** | Predefined services and pricing tiers for quick quoting |
83+
| **Milestone Payments** | Support for deposits, milestones, and recurring payments |
84+
| **Modular Workspace** | Enable only the modules you need |
85+
| **Self-Hosted** | Full control over your data with Docker deployment |
8586

8687
<br />
8788

8889
## Quick Start
8990

90-
### Docker (Recommended)
91+
### Using Docker for Services
92+
93+
The base `docker-compose.yml` runs supporting services (PostgreSQL, Mailpit) while you run Next.js locally:
9194

9295
```bash
9396
git clone https://github.com/orekoapp/oreko.git
9497
cd oreko
95-
cp .env.example .env
96-
docker-compose up -d
97-
docker-compose exec web pnpm db:migrate
98+
cp apps/web/.env.example apps/web/.env.local # Next.js loads .env.local from apps/web/
99+
docker-compose up -d # Start Postgres and Mailpit
100+
pnpm install
101+
pnpm db:migrate
102+
pnpm dev
98103
```
99104

100105
Open `http://localhost:3000`
101106

102-
### Manual Installation
107+
### Manual Installation (No Docker)
103108

104109
```bash
105110
git clone https://github.com/orekoapp/oreko.git
106111
cd oreko
107112
pnpm install
108-
cp .env.example .env
113+
cp apps/web/.env.example apps/web/.env.local # Next.js loads .env.local from apps/web/
114+
# Ensure PostgreSQL is running and DATABASE_URL is set in apps/web/.env.local
109115
pnpm db:migrate
110116
pnpm dev
111117
```
@@ -119,7 +125,6 @@ See the [full setup guide](https://oreko.app/docs) for detailed instructions.
119125
- [TypeScript](https://www.typescriptlang.org/) 5.x
120126
- [Next.js](https://nextjs.org/) 14+ (App Router)
121127
- [Prisma](https://www.prisma.io/) + [PostgreSQL](https://www.postgresql.org/)
122-
- [Redis](https://redis.io/) + [BullMQ](https://bullmq.io/)
123128
- [Shadcn UI](https://ui.shadcn.com/) + [Tailwind CSS](https://tailwindcss.com/)
124129
- [Stripe Connect](https://stripe.com/connect) for payments
125130
- [Turborepo](https://turbo.build/) monorepo
@@ -131,6 +136,8 @@ See the [full setup guide](https://oreko.app/docs) for detailed instructions.
131136

132137
We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.
133138

139+
Check `specs/PRODUCT_SPEC.md` for the roadmap and `specs/TECHNICAL_SPEC.md` for architecture details.
140+
134141
```bash
135142
# Fork, clone, then:
136143
pnpm install

‎apps/web/.env.example‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,6 @@ NEXT_PUBLIC_APP_NAME=Oreko
1111
# Database (PostgreSQL)
1212
DATABASE_URL="postgresql://oreko:oreko@localhost:5432/oreko?schema=public"
1313

14-
# Redis (required for BullMQ job queue)
15-
REDIS_URL=redis://localhost:6379
16-
1714
# Authentication (NextAuth.js)
1815
NEXTAUTH_URL=http://localhost:3000
1916
NEXTAUTH_SECRET= # Generate with: openssl rand -base64 32

‎docker-compose.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,11 @@ services:
2828
container_name: oreko-mailpit
2929
restart: unless-stopped
3030
ports:
31-
- '8025:8025' # Web UI
32-
- '1025:1025' # SMTP
31+
- '127.0.0.1:8025:8025' # Web UI
32+
- '127.0.0.1:1025:1025' # SMTP
3333
environment:
34-
MP_SMTP_AUTH_ACCEPT_ANY: 1 # Dev-only: accept any SMTP credentials
35-
MP_SMTP_AUTH_ALLOW_INSECURE: 1 # Dev-only: allow plaintext auth
34+
MP_SMTP_AUTH_ACCEPT_ANY: 1 # Dev-only: accept any SMTP credentials
35+
MP_SMTP_AUTH_ALLOW_INSECURE: 1 # Dev-only: allow plaintext auth
3636

3737
volumes:
3838
postgres_data:

0 commit comments

Comments
 (0)