Skip to content

Commit ba6af70

Browse files
authored
docs: readme polished (#723)
1 parent d79c7e9 commit ba6af70

File tree

1 file changed

+57
-31
lines changed

1 file changed

+57
-31
lines changed

README.md

Lines changed: 57 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,65 +2,76 @@
22
<img src="misc/logo-with-text.png" width="420px" alt="Flamingock logo" />
33
</p>
44

5-
65
<h3 align="center">Auditable, versioned changes across distributed systems.</h3>
76
<p align="center">Evolve queues, DBs, APIs, configs, resources and more — governed, auditable, applied at startup in lockstep.</p>
87

9-
[//]: # (<p align="center"><small><a href="https://github.com/flamingock/mongock-legacy?tab=readme-ov-file#%EF%B8%8F-mongock-is-deprecated">Coming from Mongock?</a></small></p>)
10-
11-
[//]: # (<br />)
8+
<p align="center"><small>
9+
Coming from <a href="https://github.com/flamingock/mongock-legacy#%EF%B8%8F-mongock-is-deprecated">Mongock</a>?
10+
Learn about the transition and why Flamingock is its evolution.
11+
</small></p>
1212

1313
<p align="center">
1414
<a href="https://central.sonatype.com/search?q=io.flamingock">
1515
<img src="https://img.shields.io/maven-central/v/io.flamingock/flamingock-core" alt="Maven Version" />
1616
</a>
17-
1817
<a href="https://github.com/flamingock/flamingock-java/actions/workflows/release.yml">
1918
<img src="https://github.com/flamingock/flamingock-java/actions/workflows/release.yml/badge.svg" alt="Release" />
2019
</a>
21-
2220
<a href="https://github.com/flamingock/flamingock-java/actions/workflows/build-master.yml">
2321
<img src="https://github.com/flamingock/flamingock-java/actions/workflows/build-master.yml/badge.svg" alt="Build Master" />
2422
</a>
25-
2623
<a href="https://github.com/flamingock/flamingock-java/actions/workflows/build.yml">
2724
<img src="https://github.com/flamingock/flamingock-java/actions/workflows/build.yml/badge.svg" alt="Build Dev" />
2825
</a>
29-
3026
<a href="LICENSE.md">
31-
<img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="Licence" />
27+
<img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License" />
3228
</a>
3329
</p>
3430

3531
**Flamingock** brings *Change-as-Code (CaC)* to your entire stack.
32+
3633
It applies **versioned, auditable changes** to the external systems your application depends on — such as schemas, message brokers, databases, APIs, cloud services, and any other external system your application needs.
3734

38-
Unlike infrastructure-as-code tools, Flamingock runs **inside your application** (or via the **CLI**).
39-
It ensures these systems evolve **safely, consistently, and in sync with your code at runtime**.
35+
It runs **inside your application** (or via the **CLI**) — not in CI/CD — ensuring that every environment starts with the exact data, schema, and configuration it needs to run correctly.
36+
No manual scripts. No drift. No surprises.
37+
38+
<br />
39+
40+
## 🧩 In plain English for developers
41+
42+
When you deploy an app, it often depends on things outside your code —like a database schema, a queue, or a few configuration values. Normally, keeping all of those in sync across environments means extra scripts, manual fixes, or hoping nothing drifts.
43+
44+
With **Flamingock**, your app and its changes travel together. Every update runs in order and safely, as part of the app startup — no hidden steps or guesswork.
4045

46+
If something goes wrong, Flamingock either recovers safely or stops before anything breaks.
4147

42-
### What Flamingock manages
48+
**The result**: each deployment behaves like a single, consistent package — your code and all its required changes evolve together, predictably and with peace of mind.
49+
50+
<br />
51+
52+
## 💡 What Flamingock manages
4353
Flamingock focuses on **application-level changes** that your code requires to run safely:
4454

4555
- Database schemas and reference data
4656
- Message queues and schemas
4757
- APIs and configuration values
48-
- Cloud service resources directly tied to your application
58+
- Cloud service resources directly tied to your app
4959
- Configuration changes (feature flags, secrets, runtime values)
5060

5161
### What Flamingock does *not* manage
5262
Flamingock is **not an infrastructure-as-code tool**. It does not provision servers, clusters, or networks — those belong in Terraform, Pulumi, or similar. Instead, Flamingock **complements them by handling the runtime changes your application depends on**.
5363

54-
---
64+
<br />
5565

5666
## 📦 Editions
57-
Flamingock is open source at its core, and powers three editions:
5867

59-
- **Community Edition**: Free and self-managed. Use your own audit store (e.g., MongoDB, DynamoDB). Ideal for basic change tracking.
60-
- **Cloud Edition**: Fully managed SaaS with a built-in audit store, dashboard, observability, governance, and premium features.
61-
- **Self-Hosted Edition**: Same advanced capabilities as Cloud, but deployable in your own infrastructure.
68+
Flamingock is open source at its core and powers three editions:
69+
70+
- **Community Edition (Open Source)** — Free and self-managed. Use your own audit store (e.g., MongoDB, DynamoDB). Ideal for basic change tracking.
71+
- **Cloud Edition (SaaS)** — Fully managed SaaS with a built-in audit store, dashboard, observability, governance, and premium features.
72+
- **Self-Hosted Edition** — Same enterprise-grade features as Cloud, deployable in your own infrastructure.
6273

63-
> For more information about the editions, please feel free to ask us at <a href="mailto:[email protected]">[email protected]</a>.
74+
> For inquiries about the Cloud or Self-Hosted editions, contact us at <a href="mailto:[email protected]">[email protected]</a>.
6475
6576
<br />
6677

@@ -82,24 +93,40 @@ No more fragile scripts or untracked console changes. With CaC:
8293
8394
<br />
8495

85-
## 🚀 Getting Started
96+
## 🚀 Getting started
97+
98+
```kotlin
99+
implementation(platform("io.flamingock:flamingock-community-bom:$latestVersion"))
100+
implementation("io.flamingock:flamingock-community")
86101

87-
- Read the [quick start tutorial](https://docs.flamingock.io/get-started/quick-start).
102+
annotationProcessor("io.flamingock:flamingock-processor:$latestVersion")
103+
```
88104

89-
[//]: # (- Explore real-world usage in the [examples repo]&#40;https://github.com/flamingock/flamingock-examples&#41;.)
105+
- Read the [Quick Start guide](https://docs.flamingock.io/get-started/quick-start)
106+
- Explore [examples](https://github.com/flamingock/flamingock-java-examples)
90107

91108
<br />
92109

93-
## 🔑 Key Features
110+
## 🔑 Key features
94111

112+
- **Unified system evolution**: Orchestrate changes across your full stack — event schemas, feature flags, databases, S3, SaaS APIs, and more.
95113
- **Change-as-Code (CaC)**: Treat changes to databases, queues, APIs, or configs as code — versioned, executable, and auditable.
96-
- **Unified system evolution**: Orchestrate changes across your full stack: event schemas, feature flags, databases, S3, SaaS APIs, and more.
97114
- **Programmatic or declarative**: Write changes in Java/Kotlin or define them in YAML using official or custom templates.
98-
- **Startup-Time synchronization**: Apply versioned Changes when your app starts — keeping deployments consistent and safe.
99-
- **Audit logging & rollback**: Every change is recorded externally; rollback logic is built into each Change.
100-
- **Multi-stage workflows**: Organize and execute your changes in coordinated, stage-based flows across instances.
101-
- **Native GraalVM support**: Compatible with native image builds for fast startup and low memory usage.
102-
- **Cloud-ready, OSS-Core**: Use locally, self-host, or plug into our managed Cloud — all powered by the same open source core.
115+
- **Startup-Time synchronization**: Apply versioned Changes when your app starts — ensuring environments stay consistent and safe.
116+
- **Safety by default**: When Flamingock cannot guarantee a safe outcome, it stops and requires manual intervention. No silent data corruption. Built-in rollback, and advanced safe recovery are available in the Cloud Edition.
117+
- **Audit logging**: Every change is recorded externally, with full traceability (what, when, by whom, and result).
118+
- **Cloud-ready, OSS-Core**: Use locally, self-host, or connect to our managed Cloud — all powered by the same open source foundation.
119+
- **Native GraalVM support**: Fully compatible with native image builds for fast startup and low memory usage.
120+
- **Coordinated multi-environment workflows**: Manage complex change sequences across multiple environments or application instances.
121+
122+
<br />
123+
124+
## 📘 Learn more
125+
126+
- [Official documentation](https://docs.flamingock.io)
127+
- [Quick Start guide](https://docs.flamingock.io/get-started/quick-start)
128+
- [Core concepts](https://docs.flamingock.io/get-started/core-concepts)
129+
- [Why Change-as-Code matters](https://docs.flamingock.io/get-started/Change-as-Code)
103130

104131
<br />
105132

@@ -110,7 +137,7 @@ If you'd like to report a bug, suggest a feature, or open a pull request, check
110137

111138
<br />
112139

113-
## 📢 Get Involved
140+
## 📢 Get involved
114141

115142
⭐ Star the project to show support
116143
- Report issues in the [issue tracker](https://github.com/flamingock/flamingock-java/issues)
@@ -122,4 +149,3 @@ If you'd like to report a bug, suggest a feature, or open a pull request, check
122149

123150
Flamingock is open source under the [Apache License 2.0](LICENSE.md).
124151

125-

0 commit comments

Comments
 (0)