Skip to content

docs: simplify contributing guide #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bniladridas merged 1 commit into from
Feb 18, 2026
Merged

docs: simplify contributing guide #131

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 8 additions & 162 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,172 +1,18 @@
# Contributing to Llamaware
# Contributing

Thank you for your interest in contributing to Llamaware. This guide outlines how to set up your environment, follow coding standards, and submit contributions.
This project is currently maintained by collaborators. External contributions are not accepted at this time.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The previous contributing guide included instructions for installing dependencies, which are essential for any new collaborator setting up their development environment. Removing this information makes onboarding more difficult. Please consider adding a 'Setup' section that points to the Makefile targets for dependency installation, as they provide a simple, automated way to get started.

Suggested change
## Setup
Before building, install the required dependencies for your platform using the `Makefile`:
- **macOS:** `make install-deps-mac`
- **Ubuntu:** `make install-deps-ubuntu`

## Getting started
## For Collaborators

The project uses C++20, CMake, and various libraries. It may be challenging to set up initially. We are working on improving the build process.

### Prerequisites

- C++20 compiler (GCC 10+, Clang 12+, MSVC 2019 16.11+)
- CMake 3.20+
- Git with pre-commit hook support

### Platform Dependencies

**Ubuntu/Debian**

```bash
sudo apt update
sudo apt install -y nlohmann-json3-dev cmake build-essential \
libcurl4-openssl-dev libpqxx-dev expect clang-tidy
```

**macOS**

```bash
brew install cmake nlohmann-json cpr libpqxx expect llvm
```

**Windows**

```powershell
git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
C:\vcpkg\bootstrap-vcpkg.bat
C:\vcpkg\vcpkg.exe install cpr nlohmann-json libpqxx --triplet x64-windows
```
1. Fork the repository and create a feature branch
2. Follow Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`
3. Run `make preflight` before pushing
4. Create a PR for review

### Building
## Building

```bash
# Configure
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

# Build
cmake --build build --config Release

# Run tests
cmake --build build --target test

# Run preflight
make preflight
```
Comment on lines +12 to 18
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The Makefile provides simpler, high-level targets for building and testing. The collaborator guidelines already refer to make preflight. To maintain consistency and simplify the process for developers, it would be better to use these make targets in the build instructions instead of raw cmake commands.

Suggested change
## Building
```bash
# Configure
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
# Build
cmake --build build --config Release
# Run tests
cmake --build build --target test
# Run preflight
make preflight
```
## Building
Use the `Makefile` for common development tasks:
```bash
# Build the project
make build
# Run tests
make test
# Run pre-flight checks before pushing changes
make preflight


## Development Guidelines

We are less concerned with low-level issues, such as naming conventions and indentation style. However, no topic that can help produce better code is out of bounds.

### Code Standards

- Use C++20 features appropriately
- Follow Conventional Commits (feat:, fix:, docs:, etc.)
- Apply RAII and modern C++ idioms
- Use forward declarations to reduce dependencies
- Prefer meaningful identifiers and clear comments
- Maintain exception safety and robust error handling

Our initial set of standards may be too strict. We expect to have to introduce more flexibility to better accommodate real-world needs. We also need more guidelines.

### Architecture

- Modular design with clear separation of concerns
- Service-oriented structure (Services namespace)
- Use PIMPL for ABI stability when needed
- Apply dependency injection for testability

You will find some of the architecture decisions contrary to your expectations or even contrary to your experience. If we have not suggested that you change your approach in any way, we have failed.

### Commit Format

```
type(scope): description

feat(core): add new agent mode
fix(ci): resolve windows build issue
docs(readme): update installation guide
```

Keep subject lines under 60 characters.

## Pull Request Process

We do not expect you to understand all the guidelines before trying to contribute. The rules are meant for gradual introduction into your workflow.

### Before Submitting

1. Fork the repository and create a feature branch
2. Add or update tests for your changes
3. Run all pre-commit checks
4. Verify builds across platforms
5. Update documentation if applicable

### PR Checklist

- Code follows project style guidelines
- All tests pass locally
- Pre-commit hooks pass
- CI/CD pipeline passes (Linux/macOS/Windows)
- Documentation updated
- Security considerations reviewed

### Review Process

- PRs require maintainer review
- Address feedback promptly
- Keep PRs focused and scoped
- Rebase on main before merging

## Testing

**Unit Tests**

```bash
cmake --build build --target test
```

**E2E Tests**

```bash
docker compose -f docker-compose.e2e.yml up --abort-on-container-exit
```

**Coverage**

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --target coverage
```

## Issue Reporting

### Bug Reports

- Use the bug report template
- Include OS and compiler details
- Provide minimal reproduction steps
- Attach logs or error outputs

### Feature Requests

- Use the feature request template
- Explain motivation and use case
- Consider complexity and alternatives

You will find some of our processes obvious or even trivial. Please remember that one purpose of a guideline is to help someone who is less experienced or coming from a different background or language to get up to speed.

## Security

- Report vulnerabilities via GitHub Security Advisories
- Follow secure coding best practices
- Validate all inputs and handle errors gracefully
- Use static analysis tools (clang-tidy configured)

## Getting Help

- Check existing issues and discussions
- Review documentation and examples
- Ask focused, well-researched questions

## License

By contributing, you agree that your work is licensed under the same terms as the project.
Loading