Contributing Guidelines

Relevant source files

• .github/workflows/backend-tests.yml
• .github/workflows/build-canary-image.yml
• .github/workflows/build-stable-image.yml
• .github/workflows/demo-deploy.yml
• .github/workflows/frontend-tests.yml
• .github/workflows/proto-linter.yml
• .github/workflows/stale.yml
• README.md
• scripts/Dockerfile
• scripts/entrypoint.sh
• scripts/entrypoint_test.sh

This page documents the contribution process for the Memos project, including code quality standards, testing requirements, PR workflow, and community interaction. It covers the practical mechanics of contributing code, reporting issues, and maintaining quality standards.

For setting up your development environment, see Setting Up Development Environment. For project structure and build details, see Project Structure and Build System. For testing specifics, see Testing and Quality Assurance.

---

Ways to Contribute

Memos welcomes contributions of all types. The project is fully open-source under the MIT license, and community contributions drive its development.

Contribution Types

Type	Description	Entry Point
Bug Reports	Report issues or unexpected behavior	GitHub Issues with bug template
Feature Requests	Suggest new functionality or improvements	GitHub Issues with feature template
Pull Requests	Submit code changes (fixes, features, refactoring)	Fork repository and create PR
Documentation	Improve wiki pages, README, or code comments	Edit markdown files in repository
Translations	Add or update locale files for internationalization	Edit files in web/src/locales/

The README provides direct links to contribution entry points:

• Bug reports: README.md111
• Feature requests: README.md112
• Pull requests: README.md113
• Documentation: README.md114
• Translations: README.md115

Sources: README.md105-116

---

Development Workflow

The standard contribution workflow follows GitHub's fork-and-pull model with specific quality requirements.

Contribution Flow Diagram

Sources: README.md113

Branch Strategy

• Main branch: main - always deployable, protected
• Release branches: release/x.y - stable release branches
• Feature branches: feature/description or fix/description - for development
• Topic branches: Use descriptive names that indicate the change

The CI workflows are triggered differently based on branch:

• On push to main: Runs all tests and builds canary Docker image .github/workflows/build-canary-image.yml4-5
• On push to release/**: Builds stable Docker image with version tags .github/workflows/build-stable-image.yml4-8
• On pull requests to main: Runs all quality gates .github/workflows/backend-tests.yml6-7 .github/workflows/frontend-tests.yml6-7

Sources: .github/workflows/backend-tests.yml4-7 .github/workflows/frontend-tests.yml4-7 .github/workflows/build-canary-image.yml4-5 .github/workflows/build-stable-image.yml4-8

---

Code Quality Standards

All contributions must pass automated quality gates in CI. The project enforces strict linting, formatting, and testing standards.

Quality Gates Overview

Sources: .github/workflows/backend-tests.yml .github/workflows/frontend-tests.yml .github/workflows/proto-linter.yml

Backend Quality Requirements

The backend uses GitHub Actions workflow backend-tests.yml with two job types:

Static Checks Job

The static-checks job verifies code quality without running tests:

1. Go Module Tidiness: Ensures go.mod and go.sum are properly maintained

   • Command: go mod tidy -go=1.25 .github/workflows/backend-tests.yml36-38
   • Fails if git diff shows changes

2. Golangci-lint: Comprehensive linter covering multiple Go best practices

   • Version: v2.4.0 .github/workflows/backend-tests.yml43
   • Timeout: 3 minutes .github/workflows/backend-tests.yml44
   • Uses project-specific .golangci.yml configuration

Test Matrix Job

The tests job runs four parallel test groups to optimize CI time:

Test Group	Command	Purpose
store	go test -v -coverprofile=coverage.out -covermode=atomic ./store/...	Database layer tests for all drivers
server	go test -v -race -coverprofile=coverage.out -covermode=atomic ./server/...	HTTP/gRPC service tests with race detection
plugin	go test -v -race -coverprofile=coverage.out -covermode=atomic ./plugin/...	Plugin system tests (storage backends, etc.)
other	go test -v -race -coverprofile=coverage.out -covermode=atomic ./cmd/... ./internal/... ./proto/...	Utility and infrastructure tests

Key testing flags:

• -v: Verbose output for debugging failures
• -race: Race condition detection (except store group which tests multiple DB drivers)
• -coverprofile: Generate coverage report
• -covermode=atomic: Thread-safe coverage counting

Coverage reports are uploaded to Codecov on main branch pushes: .github/workflows/backend-tests.yml86-91

Sources: .github/workflows/backend-tests.yml21-91

Frontend Quality Requirements

The frontend uses workflow frontend-tests.yml with two jobs:

1. Lint Job: Runs Biome linter

   • Command: pnpm lint in web/ directory .github/workflows/frontend-tests.yml45
   • Uses Node.js 22 and pnpm 10 .github/workflows/frontend-tests.yml16-17

2. Build Job: Verifies production build succeeds

   • Command: pnpm build in web/ directory .github/workflows/frontend-tests.yml72
   • Ensures TypeScript compilation, Vite bundling, and asset optimization work

Both jobs use frozen lockfile installation: pnpm install --frozen-lockfile .github/workflows/frontend-tests.yml41

Sources: .github/workflows/frontend-tests.yml19-73

Protocol Buffer Standards

Protocol buffer definitions must pass buf linting and formatting:

1. Buf Lint: Validates proto files against style guide

   • Uses bufbuild/buf-lint-action@v1 .github/workflows/proto-linter.yml31-33
   • Input: proto directory

2. Format Check: Ensures consistent formatting

   • Command: buf format -d .github/workflows/proto-linter.yml36-40
   • Fails if any formatting differences exist
   • Fix locally with: buf format -w

Sources: .github/workflows/proto-linter.yml15-41

---

Pull Request Process

PR Requirements Checklist

Before submitting a PR, ensure:

• Code passes all local tests (go test ./... and/or pnpm test)
• Code passes linters (golangci-lint run and/or pnpm lint)
• Commit messages are clear and descriptive (see commit guidelines below)
• PR description explains what changed and why
• PR scope is focused on a single concern (bug fix, feature, or refactoring)
• Breaking changes are documented in PR description
• New features include tests with adequate coverage
• Documentation updated if behavior changes affect users
• Protocol buffer changes include generated code updates (run buf generate)

Commit Message Guidelines

Use clear, descriptive commit messages that explain what changed and why:

Good examples:

• fix: correct memo visibility filter for protected memos
• feat: add webhook retry mechanism with exponential backoff
• refactor: extract markdown parsing into separate service
• docs: update Docker deployment section with volume syntax

Avoid:

• fix bug (too vague)
• update code (not descriptive)
• WIP (should be squashed before merging)

Format:

• Use present tense ("add feature" not "added feature")
• Keep first line under 72 characters
• Add detailed explanation in commit body if needed
• Reference issue numbers when applicable: fixes #123

PR Size and Scope

Keep pull requests focused and manageable:

• Preferred: Single logical change (one bug fix, one feature, one refactoring)
• Maximum: ~500 lines changed (excluding generated code)
• Large changes: Split into multiple PRs with clear dependencies

If your PR is large, consider:

1. Opening a GitHub issue to discuss the approach first
2. Breaking the work into smaller, reviewable chunks
3. Creating a tracking issue for multi-PR features

CI Pipeline for Pull Requests

Workflow: CI checks on pull requests to main branch

All workflows use concurrency groups with cancel-in-progress: true, automatically canceling older runs when new commits are pushed to the PR.

Sources: .github/workflows/backend-tests.yml .github/workflows/frontend-tests.yml .github/workflows/proto-linter.yml

Workflow Concurrency

All workflows use concurrency groups to cancel in-progress runs when new commits are pushed:

This prevents wasted CI resources when rapidly iterating on a PR. Each workflow-ref combination forms a unique concurrency group.

Sources: .github/workflows/backend-tests.yml13-15 .github/workflows/frontend-tests.yml11-13 .github/workflows/proto-linter.yml11-13

Path-Based Triggering

Workflows only run when relevant files change:

• Backend tests: Trigger on go.mod, go.sum, or **.go files .github/workflows/backend-tests.yml8-11
• Frontend tests: Trigger on web/** files .github/workflows/frontend-tests.yml8-9
• Proto linter: Trigger on proto/** files .github/workflows/proto-linter.yml8-9

This optimization reduces CI time for PRs that only touch specific parts of the codebase.

Sources: .github/workflows/backend-tests.yml8-11 .github/workflows/frontend-tests.yml8-9 .github/workflows/proto-linter.yml8-9

---

Code Review Expectations

Review Process

Once all CI checks pass, maintainers will review your PR. The review process typically involves:

1. Initial Triage (~1-2 days): Maintainer assigns appropriate labels and provides initial feedback

2. Technical Review (~3-5 days): Detailed code review focusing on:

   • Correctness and functionality
   • Code quality and maintainability
   • Test coverage and edge cases
   • Performance implications
   • Security considerations
   • Architectural fit

3. Iteration: Address review comments by pushing new commits to your PR branch

4. Approval: Once approved, maintainers will merge using either:

   • Squash and merge (preferred for feature branches)
   • Merge commit (for multi-commit PRs with meaningful history)

What Reviewers Look For

Backend Code Review Criteria

Aspect	What Reviewers Check
Store Layer	Proper use of Store interface, database-agnostic SQL, transaction handling
Service Layer	Correct use of gRPC service methods, proper error handling with status package
Authentication	Token validation, permission checks, proper use of context.Context for user info
Error Handling	Meaningful error messages, proper error wrapping, appropriate HTTP status codes
Resource Management	Proper cleanup of resources, context cancellation handling

Frontend Code Review Criteria

Aspect	What Reviewers Check
React Patterns	Proper hook usage, component composition, context provider hierarchy
Type Safety	Correct TypeScript types, no any usage without justification
State Management	Appropriate use of React Query for server state, context for global state
API Integration	Proper use of generated gRPC-web clients from @/grpcweb
User Experience	Loading states, error handling, optimistic updates where appropriate
Accessibility	Keyboard navigation, ARIA labels, semantic HTML

Protocol Buffer Review Criteria

• Backward compatibility with existing definitions
• Proper field numbering (never reuse removed field numbers)
• Appropriate use of optional, repeated, and oneof
• Clear field names and comments
• Run buf generate to update generated code

Response Time Expectations

• Initial response: 1-3 business days for first maintainer comment
• Review iteration: 1-2 business days between feedback cycles
• Time to merge: 1-2 weeks for typical PRs (varies by complexity)

If your PR has been waiting longer than expected:

1. Check if CI is passing and all review comments are addressed
2. Politely ping the PR thread if no response after 5 business days
3. Ask in Discord #development channel if blocked

When PRs Are Not Accepted

PRs may be closed without merging if they:

• Duplicate existing functionality without clear benefit
• Introduce unnecessary complexity or technical debt
• Break existing features or APIs without migration path
• Lack tests or fail to maintain code quality standards
• Are abandoned (no response to feedback for 14+ days)

Maintainers will provide clear reasoning when closing a PR and may suggest alternative approaches.

---

Testing Requirements

Test Coverage Expectations

The project maintains test coverage through multiple test groups. Coverage reports are generated for all test runs using:

• Coverage profile: coverage.out
• Coverage mode: atomic (thread-safe)

Coverage is uploaded to Codecov only on main branch pushes, flagged by test group: .github/workflows/backend-tests.yml86-91

Race Detection

Race condition detection is enabled for most test groups using the -race flag:

• ✓ Enabled: server, plugin, other groups .github/workflows/backend-tests.yml72-78
• ✗ Disabled: store group (tests multiple database drivers which may conflict)

Test Organization

Tests are organized by functionality:

Directory	Test Focus	Example Tests
./store/...	Database operations, migrations, driver compatibility	SQLite, MySQL, PostgreSQL tests
./server/...	HTTP/gRPC services, request handling, authentication	API endpoint tests, middleware tests
./plugin/...	Storage backends, webhook dispatchers, integrations	S3 storage tests, webhook tests
./cmd/...	CLI entry points, command parsing	Main function tests
./internal/...	Internal utilities, helpers	Utility function tests
./proto/...	Protocol buffer validation	Proto message tests

Sources: .github/workflows/backend-tests.yml64-81

Testing Scripts and Best Practices

The project includes test scripts demonstrating testing best practices. For example, entrypoint_test.sh shows:

1. Test Structure: Setup, execution, assertions, cleanup scripts/entrypoint_test.sh30-113
2. Colored Output: Visual feedback for pass/fail scripts/entrypoint_test.sh12-28
3. Cleanup: trap to remove temp files scripts/entrypoint_test.sh10
4. Exit Codes: Fail with non-zero exit if any test fails scripts/entrypoint_test.sh128-131

Sources: scripts/entrypoint_test.sh1-132

---

Security and Best Practices

Dockerfile Security Standards

The project's Dockerfile demonstrates security best practices that contributors should follow:

1. Non-root User: Application runs as UID 10001, not root scripts/Dockerfile33-34

2. Multi-stage Build: Separates build environment from runtime scripts/Dockerfile1-29

   • Build stage: golang:1.25-alpine
   • Runtime stage: alpine:3.21

3. Minimal Dependencies: Only installs required runtime packages scripts/Dockerfile32

4. Static Binary: CGO disabled for portability scripts/Dockerfile20

5. Security Flags: Binary built with security hardening scripts/Dockerfile23-24

Sources: scripts/Dockerfile1-57

Entrypoint Security Pattern

The entrypoint.sh script demonstrates secure configuration handling:

1. Secrets from Files: Supports _FILE suffix pattern for Docker secrets scripts/entrypoint.sh17-41

   • Example: MEMOS_DSN_FILE=/run/secrets/db_password reads password from file

2. Permission Fixing: Handles upgrade path from root-created files scripts/entrypoint.sh9-15

   • Fixes ownership before dropping privileges

3. Privilege Dropping: Uses su-exec to drop from root to nonroot user scripts/entrypoint.sh14

4. Validation: Checks for conflicting configuration scripts/entrypoint.sh24-27

   • Fails if both VAR and VAR_FILE are set

Sources: scripts/entrypoint.sh1-46

---

Issue Management

Creating Issues

When reporting bugs or requesting features, use the provided templates:

• Bug Reports: README.md111

  • Include Memos version, deployment method (Docker/binary), database type
  • Provide steps to reproduce
  • Attach relevant logs or screenshots

• Feature Requests: README.md112

  • Describe the use case and problem being solved
  • Explain why the feature benefits the community
  • Consider if it could be implemented as a plugin or external integration

Sources: README.md111-112

Stale Issue Policy

The project uses automated stale issue management to keep the issue tracker focused:

Configuration details:

• Stale after: 14 days of inactivity .github/workflows/stale.yml17
• Close after: 7 additional days of inactivity .github/workflows/stale.yml18
• Schedule: Runs every 8 hours .github/workflows/stale.yml5

Any comment or activity on a stale issue removes the stale label and restarts the timer.

Sources: .github/workflows/stale.yml1-19

---

Community Interaction

Communication Channels

Use the appropriate channel for different types of interaction:

Channel	Purpose	Best For	Link
GitHub Issues	Bug reports, feature requests	Tracked work items requiring code changes	Repository issues
GitHub Discussions	General questions, ideas, community support	Open-ended discussions, help requests	Repository discussions
Discord	Real-time chat, quick questions	Immediate help, community interaction	discord.gg/tfPJa4UmAv
Website	Official documentation and guides	Learning about features, deployment	usememos.com
X/Twitter	Project announcements and updates	Following project news	@usememos

When to use GitHub Issues vs Discussions:

• Issues: "X is broken", "Add feature Y", "Error Z occurs when..."
• Discussions: "How do I...", "What's the best way to...", "Should we consider..."

Sources: README.md107

Community Guidelines

When interacting in the Memos community:

1. Be Respectful: Treat all community members with respect, regardless of experience level
2. Be Patient: Maintainers and community members volunteer their time
3. Search First: Check existing issues/discussions before creating new ones
4. Provide Context: Include relevant details (version, environment, logs) when asking for help
5. Stay On Topic: Keep discussions focused on Memos-related topics
6. No Spam: Avoid promotional content unrelated to Memos

Sponsorship

The project accepts sponsorship through GitHub Sponsors to support ongoing development: README.md91

Sponsors receive:

• Recognition in README with logo placement: README.md15-37
• Priority support in Discord
• Influence on roadmap priorities

Individual and corporate sponsorships are welcome. Contact maintainers for custom sponsorship arrangements.

Sources: README.md89-91 README.md15-37

---

Release Process

Version Management

Versions follow semantic versioning (e.g., v0.28.1):

1. Tag-based releases: Git tags trigger stable image builds .github/workflows/build-stable-image.yml7-8
2. Branch-based releases: Release branches (e.g., release/0.28) build stable images .github/workflows/build-stable-image.yml5-6

Version extraction logic:

Sources: .github/workflows/build-stable-image.yml16-23

Build and Distribution

Release artifacts are distributed through multiple channels:

1. Docker Images:

   • neosmemo/memos:stable - Latest stable release
   • neosmemo/memos:canary - Latest main branch build
   • neosmemo/memos:0.28 - Specific version tags
   • ghcr.io/usememos/memos:* - GitHub Container Registry mirror

2. Binary Artifacts:

   • Built for 6 platforms: Linux (amd64, arm64, armv7), macOS (amd64, arm64), Windows (amd64)
   • Available through GitHub Actions artifacts (manual trigger)
   • Retention: 60 days .github/workflows/build-binaries.yml13

Sources: .github/workflows/build-stable-image.yml147-158 .github/workflows/build-binaries.yml97-126

Demo Environment

A demo environment is available on Render.com:

• URL: demo.usememos.com
• Deployment: Manual trigger via GitHub Actions .github/workflows/demo-deploy.yml4
• Uses Render deploy hook: .github/workflows/demo-deploy.yml11-14

Sources: README.md94 .github/workflows/demo-deploy.yml1-18

---

Summary

Contributing to Memos requires:

1. Quality Standards: Pass all CI checks (linting, tests, formatting)
2. Testing: Include tests for new features, ensure existing tests pass
3. Security: Follow security best practices for code and configuration
4. Documentation: Update docs when changing user-facing behavior
5. Community: Use appropriate channels for discussion and support

The automated CI pipeline enforces quality standards consistently. All contributions are reviewed by maintainers before merging. For questions about contributing, use GitHub Discussions or Discord.

Sources: README.md105-116