Skip to content

Commit 9ed4ddf

Browse files
anconguiancongui
committed
docs: add professional README with unified template
Standardize README.md with a consistent template including CI badge, features, installation, quick start, configuration, and documentation sections. Add paths-ignore to ci.yml to skip CI for docs-only changes.
1 parent aeeb23c commit 9ed4ddf

2 files changed

Lines changed: 112 additions & 70 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,22 @@ name: CI
22
on:
33
push:
44
branches: [develop]
5+
paths-ignore:
6+
- '**.md'
7+
- 'docs/**'
8+
- 'tutorials/**'
9+
- 'examples/**/README.md'
10+
- 'LICENSE'
11+
- '.gitignore'
512
pull_request:
613
branches: [develop, main]
14+
paths-ignore:
15+
- '**.md'
16+
- 'docs/**'
17+
- 'tutorials/**'
18+
- 'examples/**/README.md'
19+
- 'LICENSE'
20+
- '.gitignore'
721
workflow_dispatch:
822
inputs:
923
triggered-by:

‎README.md‎

Lines changed: 98 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,132 @@
11
# Firefly Framework - Parent POM
22

3-
The parent POM for all Firefly Framework modules. It centralizes dependency management, plugin configuration, and build conventions so that individual modules inherit a consistent, production-ready baseline without duplicating configuration.
3+
[![CI](https://github.com/fireflyframework/fireflyframework-parent/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-parent/actions/workflows/ci.yml)
4+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
5+
[![Java](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://openjdk.org)
6+
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot)
47

5-
## Purpose
8+
> Parent POM for the Firefly Framework providing centralized dependency management, plugin configuration, and build standards for all framework modules.
69
7-
When a Firefly Framework module (or a downstream application) declares `fireflyframework-parent` as its parent, it inherits:
10+
---
811

9-
- **Dependency version alignment** across Spring Boot, Spring Cloud, database drivers, serialization libraries, resilience utilities, and testing frameworks.
10-
- **Plugin configuration** for compilation, testing, packaging, source/javadoc generation, and OpenAPI code generation.
11-
- **Annotation processor wiring** for Lombok, MapStruct, and Spring Boot Configuration Processor.
12-
- **Consistent compiler settings** targeting Java 25 (default, Java 21+ compatible) with `-parameters` for reflection-friendly bytecode.
13-
- **Java 21 backward compatibility** via `-Pjava21` Maven profile.
12+
## Table of Contents
1413

15-
## Managed Versions
14+
- [Overview](#overview)
15+
- [Features](#features)
16+
- [Requirements](#requirements)
17+
- [Installation](#installation)
18+
- [Quick Start](#quick-start)
19+
- [Configuration](#configuration)
20+
- [Documentation](#documentation)
21+
- [Contributing](#contributing)
22+
- [License](#license)
1623

17-
### Runtime
24+
## Overview
1825

19-
| Dependency | Version |
20-
|---|---|
21-
| Spring Boot | 3.5.10 |
22-
| Spring Cloud | 2025.0.1 |
23-
| Java | 25 (default, 21+ compatible) |
24-
| SpringDoc OpenAPI | 2.8.15 |
25-
| Resilience4j | 2.3.0 |
26-
| MapStruct | 1.6.3 |
27-
| Lombok | 1.18.42 |
28-
| Logstash Logback Encoder | 8.1 |
26+
The Firefly Framework Parent POM serves as the foundational build configuration for all Firefly Framework modules. It centralizes dependency version management, plugin configurations, and build standards to ensure consistency across the entire framework ecosystem.
2927

30-
### Database
28+
By inheriting from this parent POM, all Firefly modules automatically receive managed versions for Spring Boot 3.5.x, Spring Cloud 2025.0.x, database drivers, mapping libraries, testing frameworks, and build plugins. This eliminates version conflicts and simplifies dependency management across the framework.
3129

32-
| Dependency | Version |
33-
|---|---|
34-
| PostgreSQL Driver | 42.7.8 |
35-
| R2DBC PostgreSQL | 1.0.9.RELEASE |
36-
| Flyway | 11.7.2 |
30+
The parent POM also configures annotation processors for Lombok, MapStruct, and Spring Boot Configuration Processor, along with Maven Enforcer rules requiring JDK 21+.
3731

38-
### Communication
32+
## Features
3933

40-
| Dependency | Version |
41-
|---|---|
42-
| gRPC | 1.79.0 |
43-
| Protobuf | 4.33.5 |
44-
| OpenAPI Generator | 7.19.0 |
45-
| Swagger Annotations | 2.2.42 |
34+
- Centralized dependency management for Spring Boot 3.5.x and Spring Cloud 2025.0.x
35+
- Managed versions for PostgreSQL, R2DBC, and Flyway database migrations (multi-database support)
36+
- Pre-configured annotation processors (Lombok, MapStruct, Spring Boot Configuration Processor)
37+
- OpenAPI Generator plugin configuration for server/client code generation from API specs
38+
- Maven Enforcer plugin requiring JDK 21+
39+
- Testcontainers BOM for integration testing
40+
- Resilience4j BOM for fault tolerance patterns
41+
- gRPC 1.79.x and Protobuf 4.x version management
42+
- AWS SDK 2.x, Spring Cloud Azure, and Spring Cloud GCP dependency management
43+
- SpringDoc OpenAPI for reactive API documentation
44+
- Release profile with source and Javadoc JAR generation
45+
- Java 21 backward compatibility via `-Pjava21` Maven profile
4646

47-
### Cloud Providers
47+
## Requirements
4848

49-
| Dependency | Version |
50-
|---|---|
51-
| AWS SDK | 2.41.24 |
52-
| Spring Cloud AWS | 3.4.2 |
53-
| Spring Cloud Azure | 5.24.1 |
54-
| Spring Cloud GCP | 6.5.4 |
49+
- Java 21+
50+
- Maven 3.9+
5551

56-
### Testing
52+
## Installation
5753

58-
| Dependency | Version |
59-
|---|---|
60-
| Testcontainers | 1.21.4 |
61-
| Surefire Plugin | 3.5.4 |
62-
| Failsafe Plugin | 3.5.4 |
63-
64-
## Usage
65-
66-
### As a Parent POM (Recommended)
67-
68-
Declare `fireflyframework-parent` as the parent of your module or application:
54+
Use this as a parent POM in your Firefly Framework module:
6955

7056
```xml
7157
<parent>
7258
<groupId>org.fireflyframework</groupId>
7359
<artifactId>fireflyframework-parent</artifactId>
74-
<version>1.0.0-SNAPSHOT</version>
60+
<version>26.01.01</version>
7561
<relativePath/>
7662
</parent>
7763
```
7864

79-
This gives your project all managed dependency versions, plugin configurations, and annotation processor wiring out of the box.
65+
## Quick Start
66+
67+
Create a new Firefly Framework module by referencing the parent POM:
68+
69+
```xml
70+
<?xml version="1.0" encoding="UTF-8"?>
71+
<project xmlns="http://maven.apache.org/POM/4.0.0"
72+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
73+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
74+
<modelVersion>4.0.0</modelVersion>
75+
76+
<parent>
77+
<groupId>org.fireflyframework</groupId>
78+
<artifactId>fireflyframework-parent</artifactId>
79+
<version>26.01.01</version>
80+
<relativePath/>
81+
</parent>
82+
83+
<artifactId>my-firefly-module</artifactId>
84+
85+
<dependencies>
86+
<dependency>
87+
<groupId>org.springframework.boot</groupId>
88+
<artifactId>spring-boot-starter-webflux</artifactId>
89+
</dependency>
90+
</dependencies>
91+
</project>
92+
```
8093

81-
### If You Already Have a Parent
94+
All dependency versions are inherited automatically from the parent POM.
8295

83-
If your project already has a different parent POM and cannot inherit from `fireflyframework-parent`, use the [fireflyframework-bom](https://github.com/fireflyframework/fireflyframework-bom) instead for dependency version management.
96+
## Configuration
8497

85-
## Plugin Configuration
98+
Key properties that can be overridden in child modules:
8699

87-
The parent POM configures the following plugins in `pluginManagement`:
100+
```xml
101+
<properties>
102+
<!-- Java version (default: 25) -->
103+
<java.version>25</java.version>
88104

89-
| Plugin | Purpose |
90-
|---|---|
91-
| `spring-boot-maven-plugin` | Packaging Spring Boot applications (excludes Lombok from fat JAR) |
92-
| `maven-compiler-plugin` | Java 25 (default) compilation with Lombok + MapStruct + Spring Boot Configuration Processor |
93-
| `maven-source-plugin` | Attaches source JARs to build artifacts |
94-
| `maven-javadoc-plugin` | Generates and attaches Javadoc JARs |
95-
| `maven-surefire-plugin` | Unit test execution |
96-
| `maven-failsafe-plugin` | Integration test execution |
97-
| `openapi-generator-maven-plugin` | Server/client code generation from OpenAPI specifications |
98-
| `maven-deploy-plugin` | Artifact deployment to Maven repositories |
105+
<!-- Base package for code generation -->
106+
<base.package>org.fireflyframework</base.package>
99107

100-
## License
108+
<!-- OpenAPI generation settings -->
109+
<openapi.skip.validate>false</openapi.skip.validate>
110+
<openapi.use.tags>true</openapi.use.tags>
111+
</properties>
112+
```
101113

102-
Apache License 2.0
114+
Build with Java 21 compatibility:
115+
116+
```bash
117+
mvn clean install -Pjava21
118+
```
119+
120+
## Documentation
121+
122+
No additional documentation available for this project.
123+
124+
## Contributing
125+
126+
Contributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests.
127+
128+
## License
103129

104130
Copyright 2024-2026 Firefly Software Solutions Inc.
131+
132+
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)