Skip to content

Latest commit

 

History

History
164 lines (119 loc) · 8.49 KB

CONTRIBUTING.md

File metadata and controls

164 lines (119 loc) · 8.49 KB

Contributing to Arconia

Thank you for considering contributing to Arconia! We appreciate your time and effort in helping make the project better. These guidelines aim to streamline the contribution process, ensure clarity in communication, and align your efforts with the project's goals.

Arconia is an open-source project that welcomes contributions from everyone. Whether it's reporting bugs, suggesting features, improving documentation, or submitting code changes via pull requests, your input is valuable. Please follow these guidelines to ensure a smooth and efficient collaboration.

Table of Contents

Ground Rules

  • Be Respectful. Interact politely and respectfully with everyone in the community. Adhere to the Arconia Code of Conduct.
  • Discuss First. For any non-trivial changes (more than fixing a typo), please open a GitHub Issue first. Discuss your proposed changes and get feedback before starting work. This prevents wasted effort and ensures alignment. Failure to do so might result in your pull request being rejected.
  • Use Discussions for Questions. For general questions or help, please use GitHub Discussions.
  • Focused Pull Requests. Keep each pull request focused on a single issue or feature. Link the PR to the corresponding issue (e.g., Fixes #123 or Closes gh-XXXX in the PR description).

Getting Started: Prerequisites

Before you start contributing code, ensure you have:

Contribution Workflow: Issues and Pull Requests

Contributions are made via GitHub Pull Requests. Here’s the typical workflow:

  1. Find or Create an Issue. Ensure a GitHub Issue exists for the bug or feature you want to address. If not, create one to discuss the change first (see Ground Rules).
  2. Fork and Clone. Fork the arconia-io/arconia repository on GitHub and clone your fork locally: 
    git clone https://github.com/<your-username>/arconia.git
cd arconia
  3. Create a Branch. Create a descriptive branch for your changes off the main branch: 
    git checkout -b my-descriptive-feature-branch main
  4. Implement Changes. Make your code changes. Follow the Code Style guidelines.
  5. Add Tests. Write unit or integration tests covering your changes.
  6. Update Documentation. If necessary, update documentation in the docs/ directory.
  7. Build and Test Locally. Ensure everything builds and all tests pass: 
    ./gradlew build
  • Commit Changes. Commit your work using descriptive messages that follow the Commit Messages format. Crucially, ensure your commits are signed off (see Signing Commits). 
    git add .
git commit -s -m "feat(core): Implement the new feature"
  1. Keep Branch Updated. Before pushing, and periodically during development, update your branch with the latest changes from the upstream main branch using rebase (NEVER merge): 
    # Add upstream remote if you haven't already
git remote add upstream https://github.com/arconia-io/arconia.git

# Fetch latest changes and rebase your branch
git fetch upstream
git rebase upstream/main
# Resolve any conflicts if they occur
  2. Push to Your Fork. Push your branch to your fork. Use --force-with-lease if you rebased or amended commits: 
    git push origin my-descriptive-feature-branch --force-with-lease
  3. Open a Pull Request.
    • Navigate to the arconia-io/arconia repository on GitHub.
    • Click "New pull request" and choose to compare across forks, selecting your fork and branch.
    • Target the main branch of arconia-io/arconia.
    • Ensure the PR title follows the Commit Messages format.
    • Fill out the pull request template, clearly describing the changes and linking the related issue (e.g., Fixes #123).
  4. Code Review: Project maintainers will review your PR. Address any feedback by making changes on your branch, committing them (signed-off), and pushing again. The PR will update automatically.
  5. Merge. Once the PR is approved and all checks pass, a maintainer will merge it. Congratulations and thank you for your contribution!

Reporting Bugs and Suggesting Features

Use our GitHub Issues page to report bugs or suggest features, selecting the appropriate template:

  • Bugs: Use the "Bug: Generic" template.
  • Features: Use the "Request: Feature" template.
  • Dev Services: Use the "Request: Dev Service" template.

Before submitting:

  1. Search existing issues to avoid duplicates.
  2. For bugs, ensure it's reproducible with the latest version.
  3. Provide clear descriptions and follow the template instructions.
  4. Remember to discuss significant changes before starting implementation (see Ground Rules).

Asking Support Questions

Please do not use the issue tracker for support questions. Use GitHub Discussions instead.

Reporting Security Vulnerabilities

If you discover a security vulnerability, report it responsibly by following the instructions in our Security Policy. Do NOT open a public issue or disclose it publicly.

Development Guidelines

Code Style

  • The project uses .editorconfig to define basic code formatting. Please ensure your editor respects this file.
  • Use explicit imports; avoid wildcard (*) imports.
  • Follow the existing sorting order when adding items to lists (usually alphabetical).

Commit Messages

We follow the Conventional Commits specification for PR titles and commit messages. This aids automated releases and improves history readability.

Format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
  • Types: feat, fix, docs, style, refactor, test, build, ci, chore, revert, deps.
  • Scopes (optional, relate to project modules): core, dev, k8s, multitenancy, otel. Do not include a scope if the change doesn't relate to one of these modules.
  • Description: Use present tense ("Add feature", not "Added feature") and imperative mood ("Move cursor", not "Moves cursor").
  • Breaking Changes: Indicate breaking changes with BREAKING CHANGE: in the footer or by appending ! after the type/scope (e.g., feat(core)!:).

Example: fix(dev): Correct handling of container startup timeout

The Pull Request title must also follow this convention.

Signing Commits

All commits contributed to Arconia must be signed-off, attesting to the Developer Certificate of Origin (DCO).

Commits lacking sign-off will block merging.

Developer Certificate of Origin (DCO) Sign-off

The DCO certifies you have the right to submit your contribution.

The easiest way to sign-off a commit is using the -s flag:

git commit -s -m "Your commit message"

To add a sign-off to your last commit if you forgot:

git commit --amend -s --no-edit

For older commits, use interactive rebase (git rebase -i).

Code of Conduct

All participants in the Arconia community are expected to adhere to our Code of Conduct. Please read it to understand the expected standards of behavior. Treat everyone with respect and kindness.