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:

**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:

   git checkout -b feature/my-feature
   

3. Make your changes
4. Test your changes
5. Commit with clear messages:

   git commit -m "Add support for SCRAM-SHA-1 authentication"
   

6. Push to your fork:

   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

# 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

# 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:

# 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:

/**
 * 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:

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:

// 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:

// 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! 🎉