# Contributing to @linkforty/core
Thank you for your interest in contributing to LinkForty Core! This document provides guidelines and instructions for contributing.
## Code of Conduct
We are committed to providing a welcoming and inclusive environment. Please be respectful and considerate in all interactions.
## Getting Started
### Prerequisites
- Node.js 18+ and npm
- PostgreSQL 14+
- Redis 6+ (optional but recommended)
- Git
### Development Setup
1. **Fork and clone the repository**
```bash
git clone https://github.com/YOUR_USERNAME/core.git
cd core
```
2. **Install dependencies**
```bash
npm install
```
3. **Set up environment variables**
```bash
cp .env.example .env
# Edit .env with your local database credentials
```
For self-hosted deployments behind a reverse proxy, set `TRUST_PROXY=1` (or the number of proxy hops) so client IP is taken from `X-Forwarded-For`. Client-provided `ipAddress` in the SDK install body is not used as the trusted IP (debug metadata only).
4. **Start PostgreSQL and Redis**
```bash
# Using Docker
docker compose -f examples/docker-compose.yml up -d postgres redis
```
5. **Run database migrations**
```bash
npm run migrate
```
6. **Start development server**
```bash
npm run dev
```
The server will be running at `http://localhost:3000`.
## Development Workflow
### Branch Naming
- `feature/` - New features (e.g., `feature/webhook-support`)
- `fix/` - Bug fixes (e.g., `fix/redirect-caching`)
- `docs/` - Documentation updates (e.g., `docs/api-reference`)
- `refactor/` - Code refactoring (e.g., `refactor/database-connection`)
### Commit Messages
Follow conventional commits format:
```
type(scope): description
[optional body]
[optional footer]
```
**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
**Examples:**
```
feat(analytics): add webhook support for click events
fix(redirect): cache invalidation on link update
docs(readme): update API examples
```
### Making Changes
1. **Create a new branch**
```bash
git checkout -b feature/your-feature-name
```
2. **Make your changes**
- Write clean, readable code
- Follow existing code style and patterns
- Add comments for complex logic
- Update documentation if needed
3. **Test your changes**
```bash
npm run build
npm run test # When tests are available
```
4. **Commit your changes**
```bash
git add .
git commit -m "feat(scope): description"
```
5. **Push to your fork**
```bash
git push origin feature/your-feature-name
```
6. **Create a Pull Request**
- Go to the original repository on GitHub
- Click "New Pull Request"
- Select your fork and branch
- Fill out the PR template with details
## Code Style Guidelines
### TypeScript
- Use TypeScript strict mode
- Define explicit types for function parameters and return values
- Use interfaces for object shapes
- Avoid `any` types when possible
**Example:**
```typescript
interface CreateLinkParams {
userId: string;
originalUrl: string;
title?: string;
}
async function createLink(params: CreateLinkParams): Promise