Skip to content

Commit 192d732

Browse files
Retr0-XDRetr0-XD
committed
docs: add improvements for new community contributors
- Add comprehensive Postman collection with fieldMappings and all API endpoints - Create Node.js, Python, and React example applications - Add developer integration test suite - Extend CONTRIBUTING.md with complete setup guidelines
1 parent bb2c010 commit 192d732

31 files changed

+2356
-12
lines changed

‎CONTRIBUTING.md‎

Lines changed: 211 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,41 +8,240 @@ Thanks for taking the interest in contributing ♥. We really appreciate any sup
88
- Select an issue from [here](https://github.com/revertinc/revert/issues) or create a new one
99
- Consider the results from the discussion in the issue
1010

11+
## Good First Issues
12+
13+
Looking for a place to start? Check out issues tagged with [good first issue](https://github.com/revertinc/revert/labels/good%20first%20issue). These are curated tasks suitable for new contributors.
14+
15+
## Development Setup
16+
17+
### Prerequisites
18+
19+
- Node.js 16+ (Check `.nvmrc` for the exact version)
20+
- Yarn 3.2.2 or higher
21+
- Docker & Docker Compose (for running services locally)
22+
- Git
23+
24+
### Quick Start
25+
26+
1. **Clone and Setup Repository**
27+
```bash
28+
git clone https://github.com/revertinc/revert.git
29+
cd revert
30+
nvm use # Use correct Node version from .nvmrc
31+
yarn install
32+
```
33+
34+
2. **Environment Configuration**
35+
```bash
36+
cp .env.example .env
37+
# Fill in your configuration values
38+
```
39+
40+
3. **Run Dev Environment**
41+
```bash
42+
# Using dev container (recommended)
43+
# Open repo in VS Code and use "Reopen in Container"
44+
45+
# Or manually start services
46+
docker-compose up -d
47+
yarn dev:all # Starts backend, frontend, and JS package in parallel
48+
```
49+
50+
### Backend Setup
51+
52+
Located in `packages/backend/`:
53+
54+
```bash
55+
cd packages/backend
56+
yarn install
57+
yarn dev # Runs on http://localhost:4001
58+
```
59+
60+
**Key Commands:**
61+
- `yarn build` - Production build
62+
- `yarn test` - Run tests
63+
- `yarn db:migrate` - Run database migrations
64+
- `yarn db:seed` - Seed database with test data
65+
66+
### Frontend Setup
67+
68+
Located in `packages/client/`:
69+
70+
```bash
71+
cd packages/client
72+
yarn install
73+
yarn start # Runs on http://localhost:3000
74+
```
75+
76+
### Running Tests
77+
78+
```bash
79+
# Backend tests
80+
cd packages/backend
81+
yarn test
82+
83+
# Frontend tests
84+
cd packages/client
85+
yarn test
86+
```
87+
88+
## Working with Examples
89+
90+
### Postman Collection
91+
92+
Import the Postman collection to test API endpoints:
93+
94+
1. Open Postman
95+
2. Click "Import" → "Upload Files"
96+
3. Select `/postman/revert-api.postman_collection.json`
97+
4. Configure variables (apiToken, tenantId, baseUrl)
98+
5. Start testing!
99+
100+
[Postman Collection Documentation](./postman/README.md)
101+
102+
### Example Applications
103+
104+
We provide example implementations to help you understand the API:
105+
106+
#### Node.js Example
107+
```bash
108+
cd examples/nodejs
109+
npm install
110+
cp .env.example .env
111+
# Update .env with your credentials
112+
npm start # Runs on http://localhost:3000
113+
```
114+
115+
#### Python Example
116+
```bash
117+
cd examples/python
118+
python3 -m venv venv
119+
source venv/bin/activate
120+
pip install -r requirements.txt
121+
cp .env.example .env
122+
# Update .env with your credentials
123+
python app.py # Runs on http://localhost:5000
124+
```
125+
126+
#### React Custom UI Example
127+
```bash
128+
cd examples/custom-ui
129+
npm install
130+
cp .env.example .env
131+
# Update .env with your API endpoint
132+
npm start # Runs on http://localhost:3000
133+
```
134+
135+
### Developer Test Suite
136+
137+
Run integration tests against the API:
138+
139+
```bash
140+
cd examples/dev-tester
141+
npm install
142+
cp .env.example .env
143+
# Update .env with your test credentials
144+
npm test # Runs smoke tests
145+
```
146+
11147
## Developing
12148

13-
- The development branch is <code>main</code>. All pull request should be made against this branch.
149+
### Git Workflow
150+
151+
- The development branch is <code>main</code>. All pull requests should be made against this branch.
14152
- If you need help getting started, [join us on Discord](https://discord.gg/q5K5cRhymW).
15153
- Use [Conventional Commits](https://www.conventionalcommits.org/) to keep everything nice and clean.
16154
- Choose your branch name using the issue you are working on and a conventional commit type.
17155

18-
1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your
19-
own GitHub account and then
20-
[clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
156+
1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
157+
21158
2. Create a new branch:
159+
```sh
160+
git checkout -b feat/issue-123-feature-description
161+
```
162+
163+
3. Make your changes and commit using conventional commits:
164+
```sh
165+
git add .
166+
git commit -m "feat: add new feature"
167+
git push origin feat/issue-123-feature-description
168+
```
22169

23-
- Create a new branch (include the issue id and something readable):
170+
### Pull Request Checklist
24171

25-
```sh
26-
git checkout -b feat/<feature-description>
27-
```
172+
Before submitting a PR, ensure:
28173

29-
3. See the individual [package's](https://github.com/revertinc/revert#packages) README for instructions on how to build each from source.
174+
- [ ] Branch is up to date with `main`
175+
- [ ] Code follows the project style guidelines
176+
- [ ] Changes are tested locally (`yarn test`)
177+
- [ ] All tests pass (`npm test` for examples)
178+
- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
179+
- [ ] PR description clearly describes the changes
180+
- [ ] No breaking changes (or documented in the PR)
181+
- [ ] Documentation updated (if applicable)
182+
- [ ] Examples updated (if modifying API contracts)
30183

31184
## Building
32185

33186
> **Note**
34187
> Please be sure that you can make a full production build before pushing code or creating PRs.
35188
36-
- Install the project dependencies by running:
189+
- Install dependencies:
37190
```bash
38191
yarn install
39192
```
40-
- Next, you can build the project with:
41193

194+
- Build all packages:
42195
```bash
43196
yarn build
44197
```
45198

46-
## Contributing an API Integration
199+
- Build specific package:
200+
```bash
201+
cd packages/backend
202+
yarn build
203+
```
204+
205+
## Code Quality
206+
207+
### Linting
208+
209+
```bash
210+
# Check code style
211+
yarn lint
212+
213+
# Fix linting issues
214+
yarn lint:fix
215+
```
216+
217+
### Formatting
218+
219+
The project uses Prettier for code formatting:
220+
221+
```bash
222+
# Format code
223+
yarn format
224+
225+
# Check formatting
226+
yarn format:check
227+
```
228+
229+
## Documentation
230+
231+
### API Documentation
232+
233+
API documentation is generated using Fern and available at [docs.revert.dev](https://docs.revert.dev).
234+
235+
To preview docs locally:
236+
```bash
237+
yarn fern:preview
238+
```
239+
240+
To deploy docs:
241+
```bash
242+
yarn fern:docs
243+
```
244+
245+
### Contributing an API Integration
47246

48247
See https://docs.revert.dev/overview/developer-guide/contribute-an-api-integration for more on how to contribute an integration.

‎examples/custom-ui/.env.example‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
REACT_APP_API_BASE_URL=http://localhost:3000
2+
REACT_APP_API_TOKEN=your-api-token-here
3+
REACT_APP_TENANT_ID=your-tenant-id-here

‎examples/custom-ui/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Revert API - Custom UI Example (React)
2+
3+
React application demonstrating a custom UI component for managing Revert API contacts.
4+
5+
## Setup
6+
7+
1. Copy `.env.example` to `.env` and fill in your credentials:
8+
```bash
9+
cp .env.example .env
10+
```
11+
12+
2. Install dependencies:
13+
```bash
14+
npm install
15+
```
16+
17+
## Running
18+
19+
Start the development server:
20+
```bash
21+
npm start
22+
```
23+
24+
App will open on `http://localhost:3000`
25+
26+
## Features
27+
28+
- List all contacts from Revert API
29+
- Create new contacts
30+
- Refresh contact list
31+
- Responsive table view
32+
33+
## Prerequisites
34+
35+
Ensure the Node.js example server is running on `http://localhost:3000` or update `REACT_APP_API_BASE_URL` in `.env`.
36+
37+
## Building
38+
39+
Create a production build:
40+
```bash
41+
npm run build
42+
```

‎examples/custom-ui/package.json‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
{
2+
"name": "revert-custom-ui-example",
3+
"version": "1.0.0",
4+
"description": "React custom UI example for Revert API",
5+
"private": true,
6+
"dependencies": {
7+
"axios": "^1.6.0",
8+
"dotenv": "^16.3.1",
9+
"react": "^18.2.0",
10+
"react-dom": "^18.2.0",
11+
"react-scripts": "5.0.1"
12+
},
13+
"scripts": {
14+
"start": "react-scripts start",
15+
"build": "react-scripts build",
16+
"test": "react-scripts test",
17+
"eject": "react-scripts eject"
18+
},
19+
"eslintConfig": {
20+
"extends": [
21+
"react-app"
22+
]
23+
},
24+
"browserslist": {
25+
"production": [
26+
">0.2%",
27+
"not dead",
28+
"not op_mini all"
29+
],
30+
"development": [
31+
"last 1 chrome version",
32+
"last 1 firefox version",
33+
"last 1 safari version"
34+
]
35+
}
36+
}

‎examples/custom-ui/public/index.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1" />
6+
<meta name="theme-color" content="#000000" />
7+
<meta name="description" content="Revert API Custom UI Example" />
8+
<title>Revert - Custom UI Example</title>
9+
</head>
10+
<body>
11+
<noscript>You need to enable JavaScript to run this app.</noscript>
12+
<div id="root"></div>
13+
</body>
14+
</html>

‎examples/custom-ui/src/App.css‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.App {
2+
text-align: center;
3+
}

‎examples/custom-ui/src/App.jsx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
import React from 'react';
2+
import ContactList from './components/ContactList';
3+
import './App.css';
4+
5+
function App() {
6+
return (
7+
<div className="App">
8+
<ContactList />
9+
</div>
10+
);
11+
}
12+
13+
export default App;

0 commit comments

Comments
 (0)