Contributing

Last updated: November 2025 5 min read

Contributing to Citadel

Thank you for your interest in contributing to Citadel! We welcome contributions from the community and are excited to see what you'll build.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. Please see CODE_OF_CONDUCT.md for details.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:

- **Use a clear and descriptive title** that identifies the problem
- **Describe the exact steps** which reproduce the problem in as much detail as possible
- **Provide specific examples** to demonstrate the steps, including code snippets, API calls, or configuration files
- **Describe the behavior you observed** after following the steps and point out what exactly is wrong with that behavior
- **Explain which behavior you expected** to see instead and why
- **Include screenshots or animated GIFs** if possible to help explain the problem
- **Note your environment** including OS, browser, Node.js version, Docker version, and any other relevant details
- **List any recent changes** to your configuration that might be related to the issue

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:

- **Use a clear and descriptive title** for the issue to identify the suggestion
- **Provide a step-by-step description** of the suggested enhancement in as much detail as possible
- **Provide specific examples** to demonstrate the steps or implementation
- **Describe the current behavior** and explain which behavior you expected to see instead and why
- **Explain why this enhancement** would be useful to most users
- **List some other platforms** where this enhancement exists, if applicable
- **Specify the name and version** of the OS, browser, or other relevant software you're using

Pull Requests

- **Fill in the required template** completely
- **Do not include issue numbers** in the PR title
- **Include screenshots and animated GIFs** in your pull request when possible
- **Follow the styleguides** outlined below
- **Document new code** based on the Documentation Styleguide
- **End all files with a newline**
- **Avoid platform-dependent code**
- **Write meaningful commit messages** following the Git Commit Messages styleguide
- **Include tests** for new functionality
- **Ensure all tests pass** before submitting
- **Update the README.md** if you're changing functionality

Styleguides

Git Commit Messages

- **Use the present tense** ("Add feature" not "Added feature")
- **Use the imperative mood** ("Move cursor to..." not "Moves cursor to...")
- **Limit the first line** to 72 characters or less
- **Reference issues and pull requests** liberally after the first line
- **When only changing documentation**, include [ci skip] in the commit title
- **Consider starting the commit message** with an applicable emoji:
- :art: :art: when improving the format/structure of the code
- :racehorse: :racehorse: when improving performance
- :non-potable_water: :non-potable_water: when plugging memory leaks
- :memo: :memo: when writing docs
- :penguin: :penguin: when fixing something on Linux
- :apple: :apple: when fixing something on macOS
- :checkered_flag: :checkered_flag: when fixing something on Windows
- :bug: :bug: when fixing a bug
- :fire: :fire: when removing code or files
- :green_heart: :green_heart: when fixing the CI build
- :white_check_mark: :white_check_mark: when adding tests
- :lock: :lock: when dealing with security
- :arrow_up: :arrow_up: when upgrading dependencies
- :arrow_down: :arrow_down: when downgrading dependencies
- :shirt: :shirt: when removing linter warnings

JavaScript/TypeScript Styleguide

All JavaScript and TypeScript code must adhere to Airbnb JavaScript Style Guide with the following exceptions and additions:

- **Indentation**: Use 2 spaces for indentation instead of 4
- **Line Length**: Maximum 100 characters per line
- **Semicolons**: Always use semicolons
- **Quotes**: Use single quotes for strings unless escaping is needed
- **Variables**: Prefer const over let, and let over var
- **Arrow Functions**: Use arrow functions for anonymous functions and callbacks
- **Destructuring**: Use destructuring for object and array access when possible
- **Template Literals**: Use template literals for string concatenation
- **Async/Await**: Prefer async/await over callbacks
- **TypeScript**: Use strict typing and interfaces for all public APIs
- **Comments**: Use JSDoc for all public functions and classes

Documentation Styleguide

- **Use Markdown** for all documentation
- **Reference methods and classes** in markdown with inline code formatting
- **When referring to a method**, use parentheses: authenticate()
- **When referring to a class**, do not use parentheses: CredentialVault
- **Use proper heading hierarchy** (H1, H2, H3, etc.)
- **Use code blocks** for examples with proper language specification
- **Use bullet points** for lists of items
- **Use numbered lists** for sequential steps
- **Use bold text** for important terms or warnings
- **Use italics** for emphasis or to reference files/directories

Development Setup

Prerequisites

- **Node.js 16+** (LTS recommended)
- **Docker and Docker Compose**
- **Git**
- **Code editor** (VS Code recommended)
- **PostgreSQL client** (psql)

Initial Setup

**Fork the repository** on GitHub

**Clone your fork**:

**Add upstream remote**:

**Install dependencies**:

**Start development services**:

**Run database migrations**:

Development Workflow

**Create a new branch** for your feature or bugfix:

**Make your changes** following the styleguides

**Write tests** for your changes

**Ensure all tests pass**:

**Check test coverage**:

**Commit your changes** with meaningful commit messages

**Push to your fork**:

**Open a pull request** from your fork to the main repository

Testing

We use Jest for testing with a comprehensive testing strategy:

Test Structure

`
/core
├── /src
│ ├── /__tests__ # Unit tests for services
│ └── /services
│ ├── /__tests__ # Service-specific tests
├── /integration-tests # Integration tests
└── /e2e-tests # End-to-end tests
`

Running Tests

- **Unit Tests**: npm test
- **Test Coverage**: npm test -- --coverage
- **Watch Mode**: npm test -- --watch
- **Integration Tests**: npm run test:integration
- **End-to-End Tests**: npm run test:e2e

Writing Tests

Follow the AAA pattern (Arrange, Act, Assert):

`typescript
describe('UserService', () => {
describe('createUser', () => {
it('should create a new user with valid data', async () => {
// Arrange
const userData = {
name: 'John Doe',
email: 'john@example.com',
password: 'securePassword123'
};

// Act
const user = await userService.createUser(userData);

// Assert
expect(user).toBeDefined();
expect(user.id).toBeDefined();
expect(user.name).toBe(userData.name);
});
});
});
`

Test Coverage Requirements

- **Statements**: 85% minimum coverage
- **Branches**: 80% minimum coverage
- **Functions**: 85% minimum coverage
- **Lines**: 85% minimum coverage

Code Review Process

All submissions require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Review Process

**Automated Checks**: All CI checks must pass

**Code Review**: At least one team member must approve the PR

**Security Review**: Security-sensitive changes require additional review

**Documentation**: Documentation must be updated if applicable

**Tests**: Tests must pass and maintain or improve coverage

**Style**: Code must follow our style guides

**Merge**: PR can be merged after approval

Review Criteria

Reviewers will check for:

- **Correctness**: Does the code work as intended?
- **Security**: Are there any security vulnerabilities?
- **Performance**: Is the code efficient?
- **Maintainability**: Is the code easy to understand and modify?
- **Test Coverage**: Are there adequate tests?
- **Documentation**: Is the code properly documented?
- **Style**: Does the code follow our style guides?

Additional Notes

Issue and Pull Request Labels

This section lists the labels we use to help organize and identify issues and pull requests.

#### Type of Issue and Issue State

- bug - Issues that are bugs
- enhancement - Issues that are feature requests
- documentation - Issues related to documentation
- question - Issues that are questions
- help wanted - Issues that need assistance
- good first issue - Good for newcomers
- security - Security-related issues
- performance - Performance-related issues
- refactor - Code refactoring requests
- testing - Testing-related issues

#### Pull Request Labels

- work in progress - Pull requests which are still being worked on
- needs review - Pull requests which need code review
- under review - Pull requests that are currently being reviewed
- requires changes - Pull requests which need to be updated by the author
- ready to merge - Pull requests which are ready to be merged
- security - Security-related pull requests
- breaking change - Pull requests with breaking changes

Community

Communication Channels

- **GitHub Issues**: For bug reports and feature requests
- **Discord**: Join our Discord for real-time discussions
- **Twitter**: @citadel for announcements
- **Blog**: Read our Blog for updates and tutorials

Recognition

We value all contributions and recognize contributors in several ways:

- **GitHub Contributors List**: Automatic recognition on the repository
- **Release Notes**: Mention in release notes for significant contributions
- **Community Highlights**: Featured in blog posts and social media
- **Swag Rewards**: Stickers, t-shirts, and other swag for active contributors

Mentorship

We offer mentorship opportunities for new contributors:

- **Mentorship Program**: Pair with experienced contributors
- **Code Review Guidance**: Detailed feedback on pull requests
- **Learning Resources**: Access to internal documentation and training
- **Community Events**: Participation in virtual meetups and hackathons

Resources

Documentation

- Project Overview
- Development Guide
- API Documentation
- Architecture Guide
- Security Guide
- Testing Guide

Tools and Technologies

- **Backend**: Node.js, TypeScript, Express, PostgreSQL
- **Frontend**: React, TypeScript, Vite, Tailwind CSS
- **Infrastructure**: Docker, Kubernetes, HashiCorp Vault
- **Testing**: Jest, Cypress, Artillery
- **CI/CD**: GitHub Actions, Docker Hub
- **Monitoring**: Prometheus, Grafana, ELK Stack

Learning Resources

- **TypeScript Handbook**: https://www.typescriptlang.org/docs/
- **React Documentation**: https://react.dev/
- **Node.js Documentation**: https://nodejs.org/en/docs/
- **PostgreSQL Documentation**: https://www.postgresql.org/docs/
- **Docker Documentation**: https://docs.docker.com/
- **Kubernetes Documentation**: https://kubernetes.io/docs/

Governance

Project Maintainers

The Citadel project is maintained by a team of core contributors:

- **Lead Maintainer**: [Name] - Overall project direction and architecture
- **Backend Maintainer**: [Name] - Core services and database architecture
- **Frontend Maintainer**: [Name] - Web interface and user experience
- **Security Maintainer**: [Name] - Security features and compliance
- **DevOps Maintainer**: [Name] - Infrastructure and deployment

Decision Making

Major project decisions are made through a consensus-seeking process:

**Proposal**: Create a GitHub issue or discussion for major changes

**Discussion**: Community feedback and discussion period

**Consensus**: Seek agreement among maintainers and active contributors

**Implementation**: Approved changes are implemented and reviewed

**Documentation**: All changes are properly documented

Release Process

We follow semantic versioning with regular releases:

- **Major Releases**: Breaking changes, new major features (every 6 months)
- **Minor Releases**: New features, improvements (monthly)
- **Patch Releases**: Bug fixes, security patches (weekly)

Roadmap

Our public roadmap is available in the GitHub project boards and updated quarterly. Community feedback is welcome for future planning.

Legal

License

By contributing to Citadel, you agree that your contributions will be licensed under the AGPLv3 License. See LICENSE for details.

Copyright

All contributions are subject to the project's copyright policy. Contributors retain copyright to their contributions but grant the project necessary rights under the license.

Patent Grant

Contributors grant a patent license for their contributions as specified in the AGPLv3 license.

Trademarks

The Citadel name and logo are trademarks of NBR Company LTD. Use of these trademarks is governed by separate trademark policies.

Getting Help

If you need help with contributing, please reach out through:

- **GitHub Issues**: For technical questions about the codebase
- **Discord**: For real-time assistance and discussions
- **Email**: founder@nbr.company for general contribution questions
- **Mentorship**: Request a mentor for guidance on your first contribution

Thank you for contributing to Citadel! Your efforts help make this project better for everyone.