382
CONTRIBUTING.md
Archivo normal
382
CONTRIBUTING.md
Archivo normal
@@ -0,0 +1,382 @@
|
||||
# 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! 🎉
|
||||
Referencia en una nueva incidencia
Block a user