Skip to content

Latest commit

 

History

History
123 lines (94 loc) · 2.95 KB

development.md

File metadata and controls

123 lines (94 loc) · 2.95 KB

🛠 Development Guide

Project Structure

blockcloud-backend/
├── src/
│   ├── main/
│   │   ├── java/com/blockcloud/
│   │   │   ├── BlockcloudApplication.java
│   │   │   └── HelloController.java
│   │   └── resources/
│   │       └── application.yml
├── build.gradle
└── README.md

Development Tips

  • Use Java 21 syntax and features
  • All documentation and comments should be in English
  • Build: ./gradlew build
  • Test: ./gradlew test

Code Style

  • Use @RestController or @Controller as appropriate
  • Use Lombok for reducing boilerplate code
  • Keep controller logic minimal, delegate to service layers

Running in Dev Mode

./gradlew bootRun

Hot reload is supported with DevTools if included.

Version Management (CI Automated)

  • The project uses version.properties to manage semantic version numbers.
  • The CI workflow (GitHub Actions) automatically bumps the version based on commit messages:
    • feat: → Minor version increase
    • fix: → Patch version increase
  • Example: 
    version=0.1.0 → feat → version=0.2.0

Auto-generated CHANGELOG.md

  • The file CHANGELOG.md is regenerated by CI on every version bump.
  • It includes all commit messages starting with feat: or fix: under Git tags.
  • Example: 
    ## v0.2.0
- feat: add user login

GitHub Actions Configuration

  • Workflow file: .github/workflows/version-bump.yml
  • The workflow:
    • Parses the commit message
    • Updates version.properties
    • Generates and commits CHANGELOG.md
    • Pushes changes and tags to GitHub
  • Requires permission: 
    permissions:
  contents: write

Javadoc (Code Documentation)

To generate HTML documentation from your Java source code:

./gradlew javadoc

After the build, open the following file in a browser:

build/docs/javadoc/index.html

Test Coverage with JaCoCo

The project uses JaCoCo to generate code coverage reports.

Run Tests with Coverage

./gradlew jacocoTestReport

HTML report will be generated at:

build/reports/jacoco/test/html/index.html

CI Integration

The CI workflow includes:

  • Running unit tests
  • Generating JaCoCo report
  • Uploading the report as an artifact
  • Uploading to Codecov.io

Codecov Setup

  1. Visit https://codecov.io and sign in with GitHub
  2. Add your repository (e.g. BlockCloud-dev/blockcloud-backend)
  3. Get your CODECOV_TOKEN and add it to GitHub Secrets:
    • Settings → Secrets → Actions → New repository secret
    • Name: CODECOV_TOKEN
    • Value: (paste your token)

Add Codecov Badge to README

[![codecov](https://codecov.io/gh/BlockCloud-dev/blockcloud-backend/branch/main/graph/badge.svg?token=YOUR_TOKEN_HERE)](https://codecov.io/gh/BlockCloud-dev/blockcloud-backend)

Replace YOUR_TOKEN_HERE with your actual Codecov badge token or use the auto-generated markdown from the Codecov UI.