# Contributing guide

**Want to contribute? Great!**
We try to make it easy, and all contributions, even the smaller ones, are more than welcome.
This includes bug reports, fixes, documentation, examples...
But first, read this page (including the small print at the end).

* [Legal](#legal)
* [Reporting an issue](#reporting-an-issue)
* [Before you contribute](#before-you-contribute)
  + [Code reviews](#code-reviews)
  + [Coding Guidelines](#coding-guidelines)
  + [Continuous Integration](#continuous-integration)
  + [Tests and documentation are not optional](#tests-and-documentation-are-not-optional)
* [The small print](#the-small-print)


## Legal

All original contributions to Apicurio projects are licensed under the
[ASL - Apache License](https://www.apache.org/licenses/LICENSE-2.0),
version 2.0 or later, or, if another license is specified as governing the file or directory being
modified, such other license.

All contributions are subject to the [Developer Certificate of Origin (DCO)](https://developercertificate.org/).
The DCO text is also included verbatim in the [dco.txt](dco.txt) file in the root directory of the repository.

## Reporting an issue

This project uses GitHub issues to manage the issues. Open an issue directly in GitHub.

If you believe you found a bug, and it's likely possible, please indicate a way to reproduce it, what you are seeing and what you would expect to see.
Don't forget to indicate your Apicurio Registry, Java, and Maven versions.

## Before you contribute

To contribute, use GitHub Pull Requests, from your **own** fork.

Also, make sure you have set up your Git authorship correctly:

```
git config --global user.name "Your Full Name"
git config --global user.email your.email@example.com
```

If you use different computers to contribute, please make sure the name is the same on all your computers.

We may use this information to acknowledge your contributions!

### Claiming an issue

Before you start working on an issue, let us know so we don't end up with duplicate effort:

1. **Comment on the issue** saying you'd like to work on it.
2. **Wait for a maintainer to assign it to you.** We may have context on scope, dependencies, or ongoing work that affects the approach.
3. **If someone is already assigned**, don't open a competing PR — ask in the issue whether they need help or have moved on.
4. **Stale assignments:** if an assigned issue has no PR and no update for two weeks, comment asking for a status update. If there's no response within a few days, a maintainer can reassign it.

Opening a PR on an issue that's assigned to someone else without checking first is likely to get your PR closed.

### Code reviews

All submissions, including submissions by project members, need to be reviewed by at least one Apicurio committer before being merged.

[GitHub Pull Request Review Process](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) is followed for every pull request.

### Coding Guidelines

 * We primarily use the Git history to track authorship. GitHub also has [this nice page with your contributions](https://github.com/quarkusio/quarkus/graphs/contributors).
 * Please take care to write code that fits with existing code styles.  For your convenience we have Formatters and/or Code Templates for both [Eclipse](https://github.com/Apicurio/apicurio-configs/tree/main/eclipse) and [IntelliJ](https://github.com/Apicurio/apicurio-configs/tree/main/intellij).
 * Commits should be atomic and semantic. Please properly squash your pull requests before submitting them. Fixup commits can be used temporarily during the review process but things should be squashed at the end to have meaningful commits.
 * We typically squash and merge pull requests when they are approved.  This tends to keep the commit history a little bit more tidy without placing undue burden on the developers.

### Continuous Integration

Because we are all humans, and to ensure Apicurio Registry is stable for everyone, all changes must pass continuous integration before being merged. Apicurio CI is based on GitHub Actions, which means that pull requests will receive automatic feedback.  Please watch out for the results of these workflows to see if your PR passes all tests.

### Tests and documentation are not optional

Don't forget to include tests in your pull requests.
Also don't forget the documentation (reference documentation, javadoc...).

Be sure to test your pull request using all storage variants:

1. SQL storage (using the `-Psql` profile)
2. SQL Server storage (using the `-Pmssql` profile)
3. KafkaSQL storage (using the `-Pkafkasql` profile)

### Customizing Registry supported ArtifactTypes

Apicurio Registry is a modular project and allows reuse of artifact types to extend and enhance functionality.

You can modify the currently supported artifact types and add new types by providing a higher priority implementation of `io.apicurio.registry.types.<my-type>.provider.ArtifactTypeUtilProviderImpl` to the dependency injection framework.

In [this GitHub repository](https://github.com/andreaTP/apicurio-registry-with-bigquery-example), you can find an example where we add demo `BigQuery` support.

The important parts are as follows:

 - Use [Apicurio Registry as a dependency](https://github.com/andreaTP/apicurio-registry-with-bigquery-example/blob/66c5d18d9c0b5e246597b79e5c5b82a54752a65d/pom.xml#L45-L49)
 - Provide a [higher priority `ArtifactTypeUtilProviderImpl`](https://github.com/andreaTP/apicurio-registry-with-bigquery-example/blob/66c5d18d9c0b5e246597b79e5c5b82a54752a65d/src/main/java/io/apicurio/registry/types/bigquery/provider/ArtifactTypeUtilProviderImpl.java#L30-L33)
 - [Update the provider list](https://github.com/andreaTP/apicurio-registry-with-bigquery-example/blob/66c5d18d9c0b5e246597b79e5c5b82a54752a65d/src/main/java/io/apicurio/registry/types/bigquery/provider/ArtifactTypeUtilProviderImpl.java#L48) in the constructor to include the additional artifact type

**NOTES:**

- When creating an artifact of a type that is not included in the default, you must _always_ specify the appropriate artifact type.
- The registry UI will show the plain name of the additional type and won't have an appropriate icon to identify it.

## Versioning & Release Cycle

Apicurio Registry uses [Semantic Versioning](https://semver.org/) with a clear split between minor and patch releases:

| Release type | Contains | Example |
|--------------|----------|---------|
| **Minor** (3.3.0 → 3.4.0) | New features, enhancements, bug fixes | Scheduled development milestones |
| **Patch** (3.3.0 → 3.3.1) | CVE / security fixes only | Dependency upgrades, security patches |

### Support window

We maintain the **latest two minor versions** with security patches. Once a new minor is released, the oldest supported minor reaches end-of-life.

### Branch strategy

| Branch | Purpose |
|--------|---------|
| `main` | Active development — next minor release |
| `3.3.x` | Maintenance branch for 3.3 patch releases (created when 3.4.0 development starts) |

### Where to target your PR

- **Features and bug fixes** → target `main`
- **CVE / security backports for N-1** → target the maintenance branch (e.g., `3.3.x`), cherry-picked from the fix on `main`
- Bug fix backports are **not** accepted on maintenance branches — patches are strictly CVE-only

## The small print

This project is an open source project. Please act responsibly, be nice, polite and enjoy!
