Skip to content

Commit 003b18a

Browse files
hanoakhanoak
committed
chore: Added CONTRIBUTING.md file
1 parent 35fbe57 commit 003b18a

1 file changed

Lines changed: 399 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 399 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,399 @@
1+
# Contributing to contentstack-webhook-verify
2+
3+
Thank you for your interest in contributing to `contentstack-webhook-verify`! This document provides guidelines and instructions for setting up the development environment and contributing to the project.
4+
5+
## Table of Contents
6+
7+
- [Development Setup](#development-setup)
8+
- [Project Structure](#project-structure)
9+
- [Development Workflow](#development-workflow)
10+
- [Code Standards](#code-standards)
11+
- [Testing](#testing)
12+
- [Submitting Changes](#submitting-changes)
13+
- [Release Process](#release-process)
14+
15+
## Development Setup
16+
17+
### Prerequisites
18+
19+
Before you begin, ensure you have the following installed:
20+
21+
- **Node.js** (v18.0.0 or higher)
22+
- **npm** (v8.0.0 or higher)
23+
- **Git**
24+
25+
### Getting Started
26+
27+
1. **Fork and Clone the Repository**
28+
29+
```bash
30+
# Fork the repository on GitHub, then clone your fork
31+
git clone https://github.com/hanoak/contentstack-webhook-verify.git
32+
cd contentstack-webhook-verify
33+
```
34+
35+
2. **Install Dependencies**
36+
37+
```bash
38+
npm install
39+
```
40+
41+
3. **Build the Project**
42+
43+
```bash
44+
npm run build
45+
```
46+
47+
4. **Verify Setup**
48+
49+
```bash
50+
# Check if TypeScript compilation works
51+
npm run build
52+
53+
# Run linting
54+
npm run lint:fix
55+
56+
# Format code
57+
npm run prettify
58+
```
59+
60+
### Environment Configuration
61+
62+
This project uses the following configuration files:
63+
64+
- **TypeScript**: `tsconfig.json`
65+
- **ESLint**: `eslint.config.js`
66+
- **Prettier**: `.prettierrc` (if exists) or default configuration
67+
- **Git Hooks**: `.lintstagedrc.json` for pre-commit hooks
68+
- **Husky**: Pre-commit hooks configuration in `package.json`
69+
70+
## Project Structure
71+
72+
```text
73+
contentstack-webhook-verify/
74+
├── src/ # Source code
75+
│ ├── index.ts # Main entry point
76+
│ ├── config/ # Default configuration
77+
│ │ └── index.ts
78+
│ ├── constants/ # Constants and regions
79+
│ │ └── index.ts
80+
│ ├── types/ # TypeScript type definitions
81+
│ │ └── index.ts
82+
│ └── utils/ # Utility functions
83+
│ ├── error.ts # Custom error class
84+
│ ├── replay-verify.ts
85+
│ ├── request.ts # HTTP request handling
86+
│ ├── signature-verify.ts
87+
│ └── validate.ts # Input validation
88+
├── dist/ # Compiled JavaScript (generated)
89+
├── .lintstagedrc.json # Lint-staged configuration
90+
├── eslint.config.js # ESLint configuration
91+
├── tsconfig.json # TypeScript configuration
92+
├── package.json # Project configuration
93+
└── README.md # Project documentation
94+
```
95+
96+
## Development Workflow
97+
98+
### Branch Naming Convention
99+
100+
Use descriptive branch names with the following prefixes:
101+
102+
- `feature/` - New features
103+
- `fix/` - Bug fixes
104+
- `docs/` - Documentation updates
105+
- `refactor/` - Code refactoring
106+
- `test/` - Testing improvements
107+
108+
Examples:
109+
110+
```bash
111+
git checkout -b feature/add-custom-headers-support
112+
git checkout -b fix/signature-validation-edge-case
113+
git checkout -b docs/update-api-reference
114+
```
115+
116+
### Available Scripts
117+
118+
| Script | Description |
119+
| ------------------- | -------------------------------------- |
120+
| `npm run build` | Compile TypeScript to JavaScript |
121+
| `npm run prepare` | Automatic build before publishing |
122+
| `npm run lint:fix` | Run ESLint and fix auto-fixable issues |
123+
| `npm run prettify` | Format code with Prettier |
124+
| `npm run precommit` | Run pre-commit checks |
125+
126+
### Making Changes
127+
128+
1. **Create a Feature Branch**
129+
130+
```bash
131+
git checkout -b feature/your-feature-name
132+
```
133+
134+
2. **Make Your Changes**
135+
- Write code following the established patterns
136+
- Add TypeScript types for any new interfaces
137+
- Update documentation if needed
138+
139+
3. **Test Your Changes**
140+
141+
```bash
142+
# Build the project
143+
npm run build
144+
145+
# Run linting
146+
npm run lint:fix
147+
148+
# Format code
149+
npm run prettify
150+
```
151+
152+
4. **Commit Your Changes**
153+
154+
The project uses Husky for pre-commit hooks that will automatically:
155+
- Run Prettier on all files
156+
- Run ESLint on TypeScript files
157+
- Ensure code quality before commits
158+
159+
```bash
160+
git add .
161+
git commit -m "feat: add support for custom headers"
162+
```
163+
164+
## Code Standards
165+
166+
### TypeScript Guidelines
167+
168+
- Use strict TypeScript configuration
169+
- Define explicit types for all function parameters and return values
170+
- Use interfaces for object shapes
171+
- Prefer `const` assertions where appropriate
172+
- Use meaningful variable and function names
173+
174+
### Code Style
175+
176+
The project uses:
177+
178+
- **Prettier** for code formatting
179+
- **ESLint** for code quality and consistency
180+
- **TypeScript** strict mode
181+
182+
Key style preferences:
183+
184+
- Use double quotes for strings
185+
- Use semicolons
186+
- 2-space indentation
187+
- Trailing commas in multiline structures
188+
189+
### File Naming
190+
191+
- Use kebab-case for file names: `signature-verify.ts`
192+
- Use PascalCase for class names: `WebhookError`
193+
- Use camelCase for function and variable names: `verifySignature`
194+
- Use SCREAMING_SNAKE_CASE for constants: `CS_REGIONS`
195+
196+
### Documentation
197+
198+
- Use JSDoc comments for all public functions
199+
- Include parameter descriptions and return types
200+
- Add usage examples for complex functions
201+
- Keep README.md updated with any changes
202+
203+
Example JSDoc:
204+
205+
```typescript
206+
/**
207+
* Verifies the authenticity of a webhook request signature.
208+
*
209+
* @param headerSignature - The signature from the webhook header
210+
* @param publicKey - The public key for verification
211+
* @param requestBody - The webhook request body
212+
* @throws {WebhookError} When signature verification fails
213+
*/
214+
```
215+
216+
### Error Handling
217+
218+
- Use the custom `WebhookError` class for all webhook-related errors
219+
- Provide descriptive error messages
220+
- Include context in error messages when helpful
221+
- Handle edge cases gracefully
222+
223+
## Testing
224+
225+
### Manual Testing
226+
227+
For now, the project relies on manual testing:
228+
229+
1. **Build the project** to ensure TypeScript compilation works
230+
2. **Run linting** to catch potential issues
231+
3. **Test with real webhook payloads** if possible
232+
233+
### Future Testing Plans
234+
235+
We welcome contributions to add:
236+
237+
- Unit tests with Jest or similar
238+
- Integration tests
239+
- Mock webhook payload testing
240+
- Automated CI/CD pipeline
241+
242+
## Submitting Changes
243+
244+
### Pull Request Process
245+
246+
1. **Ensure Your Fork is Up to Date**
247+
248+
```bash
249+
git remote add upstream https://github.com/hanoak/contentstack-webhook-verify.git
250+
git fetch upstream
251+
git checkout main
252+
git merge upstream/main
253+
```
254+
255+
2. **Push Your Changes**
256+
257+
```bash
258+
git push origin feature/your-feature-name
259+
```
260+
261+
3. **Create a Pull Request**
262+
- Go to GitHub and create a pull request
263+
- Use a descriptive title and description
264+
- Reference any related issues
265+
- Include testing instructions if applicable
266+
267+
### Pull Request Guidelines
268+
269+
- **Title**: Use conventional commit format: `feat:`, `fix:`, `docs:`, etc.
270+
- **Description**: Explain what changes were made and why
271+
- **Testing**: Describe how to test the changes
272+
- **Breaking Changes**: Clearly mark any breaking changes
273+
274+
Example PR description:
275+
276+
```markdown
277+
## Description
278+
279+
Adds support for custom HTTP headers in webhook verification requests.
280+
281+
## Changes
282+
283+
- Added `customHeaders` option to `ConfigOptions`
284+
- Updated request utility to include custom headers
285+
- Added TypeScript types for new option
286+
- Updated documentation with usage examples
287+
288+
## Testing
289+
290+
- Built project successfully
291+
- Tested with custom headers in development environment
292+
- All existing functionality remains unchanged
293+
294+
## Breaking Changes
295+
296+
None - this is a backward-compatible addition.
297+
```
298+
299+
### Code Review Process
300+
301+
1. All pull requests require review before merging
302+
2. Address any feedback from reviewers
303+
3. Ensure all checks pass (linting, building)
304+
4. I will merge approved PRs
305+
306+
## Release Process
307+
308+
### Versioning
309+
310+
This project follows [Semantic Versioning](https://semver.org/):
311+
312+
- **MAJOR** version for incompatible API changes
313+
- **MINOR** version for backwards-compatible functionality
314+
- **PATCH** version for backwards-compatible bug fixes
315+
316+
### Release Steps
317+
318+
1. Update version in `package.json`
319+
2. Update `CHANGELOG.md` (if exists)
320+
3. Create a git tag
321+
4. Publish to npm registry
322+
323+
## Development Tips
324+
325+
### IDE Setup
326+
327+
**VS Code Extensions** (recommended):
328+
329+
- TypeScript and JavaScript Language Features
330+
- ESLint
331+
- Prettier - Code formatter
332+
- Auto Import - ES6, TS, JSX, TSX
333+
334+
### Debugging
335+
336+
- Use `console.log` for debugging during development
337+
- Remove debug logs before committing
338+
- Use TypeScript's strict mode to catch potential issues early
339+
340+
### Performance Considerations
341+
342+
- Keep the library lightweight with no runtime dependencies
343+
- Optimize for common use cases
344+
- Consider memory usage in long-running applications
345+
346+
## Getting Help
347+
348+
### Communication Channels
349+
350+
- **GitHub Issues**: For bug reports and feature requests
351+
- **GitHub Discussions**: For questions and general discussion
352+
- **Pull Request Comments**: For code-specific discussions
353+
354+
### Common Issues
355+
356+
**Build Failures:**
357+
358+
- Ensure Node.js version is compatible
359+
- Clear `node_modules` and reinstall: `rm -rf node_modules package-lock.json && npm install`
360+
- Check TypeScript compilation errors
361+
362+
**Linting Errors:**
363+
364+
- Run `npm run lint:fix` to auto-fix issues
365+
- Check ESLint configuration if new rules are needed
366+
367+
**Pre-commit Hook Failures:**
368+
369+
- Fix linting and formatting issues
370+
- Ensure all files are properly staged
371+
- Check Husky configuration if hooks aren't running
372+
373+
## Code of Conduct
374+
375+
### Our Standards
376+
377+
- Be respectful and inclusive
378+
- Focus on constructive feedback
379+
- Help others learn and grow
380+
- Maintain a professional environment
381+
382+
### Reporting Issues
383+
384+
If you encounter any behavior that violates our standards, please report it by:
385+
386+
- Opening a GitHub issue
387+
- Contacting the project maintainers directly
388+
389+
## Recognition
390+
391+
Contributors will be recognized in:
392+
393+
- GitHub contributor list
394+
- Release notes for significant contributions
395+
- Special mentions for outstanding contributions
396+
397+
---
398+
399+
Thank you for contributing to `contentstack-webhook-verify`! Your contributions help make webhook security more accessible to the developer community.

0 commit comments

Comments
 (0)