prosody-nodejs/CONTRIBUTING.md

# Contributing to Prosody Node.js

Thank you for your interest in contributing to Prosody Node.js! This document provides guidelines and instructions for contributing.

## Code of Conduct

- Be respectful and inclusive
- Welcome newcomers
- Focus on constructive feedback
- Assume good intentions

## How to Contribute

### Reporting Bugs

Before creating a bug report, please check existing issues. When creating a bug report, include:

- **Clear title and description**
- **Steps to reproduce** the issue
- **Expected behavior** vs actual behavior
- **Environment details** (OS, Node.js version, etc.)
- **Logs** if applicable

Example:
```markdown
**Description**: Server crashes when connecting with invalid credentials

**Steps to Reproduce**:
1. Start server with `npm start`
2. Connect with client using invalid password
3. Server crashes with error

**Expected**: Server should reject connection gracefully

**Environment**:
- OS: Ubuntu 22.04
- Node.js: v18.17.0
- Version: 1.0.0

**Logs**:
```
Error: Cannot read property 'jid' of undefined
  at Session.authenticate (session-manager.js:123)
```
```

### Suggesting Features

Feature requests are welcome! Please include:

- **Use case**: Why is this feature needed?
- **Description**: What should it do?
- **Examples**: How would it be used?
- **Alternatives**: What alternatives exist?

### Pull Requests

1. **Fork** the repository
2. **Create a branch** from `main`:
   ```bash
   git checkout -b feature/my-feature
   ```
3. **Make your changes**
4. **Test your changes**
5. **Commit** with clear messages:
   ```bash
   git commit -m "Add support for SCRAM-SHA-1 authentication"
   ```
6. **Push** to your fork:
   ```bash
   git push origin feature/my-feature
   ```
7. **Create Pull Request** on GitHub

## Development Setup

### Prerequisites

- Node.js 18+
- Git
- Text editor (VS Code recommended)

### Setup

```bash
# Clone your fork
git clone https://github.com/your-username/prosody-nodejs.git
cd prosody-nodejs

# Install dependencies
npm install

# Create environment file
cp .env.example .env

# Run in development mode
npm run dev
```

### Running Tests

```bash
# Run all tests
npm test

# Run specific test file
npm test -- session-manager.test.js

# Run with coverage
npm test -- --coverage

# Watch mode
npm test -- --watch
```

### Code Style

We use ESLint and Prettier:

```bash
# Check style
npm run lint

# Fix style issues
npm run lint -- --fix

# Format code
npm run format
```

### Code Standards

- Use **ES6+** features
- Use **async/await** for asynchronous code
- Add **JSDoc comments** for public APIs
- Write **meaningful variable names**
- Keep functions **small and focused**
- Handle **errors properly**

Example:

```javascript
/**
 * Authenticate a session with credentials
 * @param {string} sessionId - Session identifier
 * @param {string} username - Username
 * @param {string} password - Password
 * @returns {Promise<boolean>} True if authenticated
 * @throws {AuthenticationError} If authentication fails
 */
async authenticateSession(sessionId, username, password) {
  if (!sessionId || !username || !password) {
    throw new Error('Missing required parameters');
  }
  
  try {
    const session = this.getSession(sessionId);
    if (!session) {
      throw new AuthenticationError('Session not found');
    }
    
    // Authenticate...
    return true;
  } catch (error) {
    this.logger.error('Authentication failed:', error);
    throw error;
  }
}
```

## Project Structure

```
prosody-nodejs/
├── src/
│   ├── core/        # Core server components
│   ├── modules/     # XMPP modules
│   ├── storage/     # Storage backends
│   └── utils/       # Utilities
├── test/            # Test files
├── docs/            # Documentation
└── examples/        # Examples
```

## What to Contribute

### High Priority

- **Core Modules**: roster, disco, vcard, private
- **Storage Backends**: PostgreSQL, MongoDB
- **Authentication**: SCRAM-SHA-1, SCRAM-SHA-256
- **S2S Federation**: Complete implementation
- **BOSH**: Full implementation
- **WebSocket**: Full implementation

### Medium Priority

- **XEPs**: MAM, MUC, PubSub, HTTP Upload
- **Admin Interface**: Web-based admin panel
- **Metrics**: Prometheus metrics
- **Clustering**: Multi-instance support

### Low Priority

- **Additional Features**: Various XEPs
- **Performance**: Optimizations
- **Documentation**: Improvements
- **Examples**: More examples

## Module Development

To create a new module:

1. Create file in `src/modules/mod_yourmodule.js`
2. Follow the module template:

```javascript
module.exports = {
  name: 'yourmodule',
  version: '1.0.0',
  description: 'Your module description',
  author: 'Your Name',
  dependencies: [],
  
  load(module) {
    const { logger, stanzaRouter } = module.api;
    
    logger.info('Your module loaded');
    
    // Add your functionality
  },
  
  unload(module) {
    module.api.logger.info('Your module unloaded');
  }
};
```

3. Add tests in `test/modules/mod_yourmodule.test.js`
4. Document in `docs/MODULES.md`

## Testing

### Unit Tests

Test individual components:

```javascript
// test/core/session-manager.test.js
const SessionManager = require('../../src/core/session-manager');

describe('SessionManager', () => {
  let manager;
  
  beforeEach(() => {
    manager = new SessionManager({});
  });
  
  it('should create a session', () => {
    const session = manager.createSession({
      id: 'test-123',
      jid: 'user@localhost'
    });
    
    expect(session).toBeDefined();
    expect(session.jid).toBe('user@localhost');
  });
});
```

### Integration Tests

Test component interaction:

```javascript
// test/integration/c2s.test.js
const Server = require('../../src/core/server');
const { Client } = require('@xmpp/client');

describe('C2S Integration', () => {
  let server;
  
  beforeAll(async () => {
    server = new Server(config);
    await server.start();
  });
  
  afterAll(async () => {
    await server.stop();
  });
  
  it('should accept client connection', async () => {
    const client = new Client({...});
    await client.connect();
    expect(client.online).toBe(true);
  });
});
```

## Documentation

- Update **README.md** for major features
- Add **API documentation** in `docs/API.md`
- Create **guides** for new features
- Add **examples** for common use cases
- Update **CHANGELOG.md**

## Commit Messages

Use clear, descriptive commit messages:

### Format

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Types

- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation
- **style**: Code style (formatting)
- **refactor**: Code refactoring
- **test**: Tests
- **chore**: Maintenance

### Examples

```
feat(auth): add SCRAM-SHA-1 authentication

Implement SCRAM-SHA-1 authentication mechanism according to RFC 5802.
Includes challenge-response handling and credential storage.

Closes #123
```

```
fix(session): prevent crash on invalid JID

Add validation for JID format before session creation.
Throw appropriate error for invalid JIDs.

Fixes #456
```

## Release Process

1. Update version in `package.json`
2. Update `CHANGELOG.md`
3. Create git tag: `git tag v1.0.0`
4. Push tag: `git push origin v1.0.0`
5. Create GitHub release
6. Publish to npm (if applicable)

## Community

- **GitHub Discussions**: Ask questions, share ideas
- **GitHub Issues**: Report bugs, request features
- **XMPP Chat**: prosody-nodejs@conference.example.com

## Questions?

If you have questions:

1. Check the documentation in `docs/`
2. Search existing issues
3. Ask in GitHub Discussions
4. Join XMPP chat room

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

## Thank You!

Your contributions make Prosody Node.js better for everyone. Thank you for taking the time to contribute! 🎉