Contributing to OrbitRepos¶

Thank you for your interest in contributing to OrbitRepos! We welcome contributions from everyone, whether it's fixing a bug, improving documentation, or adding new features.

This guide will help you get started with the development process and explain our workflow and conventions.

Getting Started¶

Prerequisites¶

To build and run OrbitRepos locally, you'll need the following installed:

Go 1.24+: The backend is written in Go.
Node.js 20+: The frontend is built with React and TypeScript.
PostgreSQL 16: Used as the primary metadata store.
Docker: Required for building images and running integration tests.

Fork and Clone¶

Fork the repository on GitHub.

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/OrbitRepos.git
cd OrbitRepos

Add the original repository as a remote:

git remote add upstream https://github.com/vanlongme/OrbitRepos.git

Dev Setup¶

Download Go dependencies:
```
make deps
```
Install frontend dependencies:
```
cd web && npm install && cd ..
```
Set up a local PostgreSQL database and update your configuration in configs/orbitrepo.yaml or use environment variables.

Development Workflow¶

Make Commands¶

We use a Makefile to automate common development tasks. Here are the most important commands:

Command	Description
`make deps`	Download Go dependencies
`make web`	Build the React web UI
`make build`	Build the Go binary
`make test`	Run all tests (unit and race detection)
`make lint`	Run `golangci-lint` on the backend
`make migrate-up`	Run database migrations up
`make run`	Build and run the application
`make dev`	Run with hot reload (requires `air`)
`make docker-build`	Build the Docker image locally

Project Structure¶

A high-level overview of the project structure:

cmd/orbitrepo/: The entry point for the application.
internal/: Private application code.
- api/: REST API handlers and middleware.
- auth/: Authentication services (Local, LDAP, OIDC).
- database/: Database connection and migrations.
- format/: Handlers for different repository formats (Docker, Maven, npm, etc.).
- repository/: Business logic for repositories and artifacts.
- storage/: Storage backend implementations (Filesystem, S3).
web/: The React + TypeScript frontend.
deployments/: Dockerfile and Docker Compose configurations.
docs/: Project documentation.

For a deeper dive into the architecture, see the Architecture Documentation.

Running Locally¶

To run OrbitRepos locally for development:

Ensure you have a PostgreSQL database running.
Run migrations:
```
make migrate-up
```
Build the web UI:
```
make web
```
Start the application:
```
make run
```

Alternatively, use make dev if you have air installed for hot-reloading during backend development.

Code Style¶

Go Conventions¶

Follow standard Go formatting (gofmt).
Run make lint before submitting a PR.
Write unit tests for new logic in *_test.go files.
Use descriptive variable and function names.

React/TypeScript Conventions¶

Use functional components and hooks.
Ensure all new components are properly typed with TypeScript.
Maintain consistent styling using the project's CSS-in-JS or Tailwind configuration (if applicable).
Run npm run lint in the web directory.

Commit Message Format¶

We follow the Conventional Commits specification:

feat: A new feature
fix: A bug fix
docs: Documentation changes
style: Changes that do not affect the meaning of the code (white-space, formatting, etc.)
refactor: A code change that neither fixes a bug nor adds a feature
test: Adding missing tests or correcting existing tests
chore: Changes to the build process or auxiliary tools

Example: feat: add support for NuGet V3 feeds

Pull Request Process¶

Branch Naming¶

Use descriptive branch names: * feature/your-feature-name * fix/bug-description * docs/improvement-name

PR Checklist¶

Before submitting a PR, please ensure: 1. Your code follows the project's style guidelines. 2. You have added tests for your changes. 3. All tests pass (make test). 4. Linter passes (make lint). 5. Documentation is updated if necessary.

Review Process¶

Once you submit a PR, it will be reviewed by the maintainers. They may request changes or ask questions. Once approved, your PR will be merged into the main branch.

Reporting Issues¶

Bug Reports¶

If you find a bug, please open an issue and include: * A clear and descriptive title. * Steps to reproduce the problem. * Expected behavior vs. actual behavior. * Screenshots if applicable. * Your environment (OS, Go version, Node version).

Feature Requests¶

We'd love to hear your ideas for new features! When requesting a feature, please: * Explain the use case and why this feature would be useful. * Describe how you imagine the feature working.

Thank you for contributing to OrbitRepos!