diff --git a/.circleci/config.yml b/.circleci/config.yml deleted file mode 100644 index 74940a5a754..00000000000 --- a/.circleci/config.yml +++ /dev/null @@ -1,26 +0,0 @@ -version: 2 -jobs: - build: - branches: - only: - - master - - develop - - addinCircleCI - - docker: - - image: circleci/openjdk:8-jdk-browsers - working_directory: ~/java-tron - steps: - - checkout - - run: - name: multi_os_result - command: echo "curl http://60.205.215.34/multi_os_result" -# -# - run: -# name: Daily Build Report -# command: curl http://47.95.206.44:50080/Daily_Build_Task_Report -# -# - run: -# name: Download Links -# command: sh DownloadLinks.sh - diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000000..d171944d877 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,3 @@ +./* +!docker-entrypoint.sh + diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index 6d82a3ae6a9..00000000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,13 +0,0 @@ - - -### 1. What did you do? - - - -### 2. What did you expect to see? - - - -### 3. What did you see instead? - - diff --git a/.github/ISSUE_TEMPLATE/ask-a-question.md b/.github/ISSUE_TEMPLATE/ask-a-question.md new file mode 100644 index 00000000000..1517046d7da --- /dev/null +++ b/.github/ISSUE_TEMPLATE/ask-a-question.md @@ -0,0 +1,51 @@ +--- +name: Ask a question +about: Something is unclear or needs clarification +title: '[Question]' +labels: 'type:docs' +assignees: '' + +--- + + + +## Question + + + +## Context + + + +**What are you trying to achieve?** + + +**What have you tried so far?** + + +**Relevant documentation or code** + + +## Environment (if applicable) + +- Network: +- java-tron version: +- Operating System: +- Java version: + +## Additional Information (Optional) + + diff --git a/.github/ISSUE_TEMPLATE/report-a-bug.md b/.github/ISSUE_TEMPLATE/report-a-bug.md new file mode 100644 index 00000000000..30a3b245862 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/report-a-bug.md @@ -0,0 +1,86 @@ +--- +name: Report a bug +about: Create a report to help us improve +title: '[Bug]' +labels: 'type:bug' +assignees: '' + +--- + + + +## Bug Description + + + +## Environment + +**Network** + + +**Software Versions** + + +``` +OS: +JVM: +Git Commit: +Version: +Code: +``` + +**Configuration** + + +## Expected Behavior + + + +## Actual Behavior + + + +## Frequency + + +- [ ] Always (100%) +- [ ] Frequently (>50%) +- [ ] Sometimes (10-50%) +- [ ] Rarely (<10%) + +## Steps to Reproduce + + + +1. +2. +3. + +## Logs and Error Messages + + + +``` +[Paste error messages, stack traces, or relevant logs here] +``` + +## Additional Context (Optional) + + + +**Screenshots** + + +**Related Issues** + + +**Possible Solution** + diff --git a/.github/ISSUE_TEMPLATE/request-a-feature.md b/.github/ISSUE_TEMPLATE/request-a-feature.md new file mode 100644 index 00000000000..d8234f92a25 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/request-a-feature.md @@ -0,0 +1,47 @@ +--- +name: Request a feature +about: Suggest an idea for this project +title: '[Feature]' +labels: 'type:feature' +assignees: '' + +--- + +# Summary + + +# Problem +### Motivation + + +### Current State + + +### Limitations or Risks + + +# Proposed Solution + +### Proposed Design + + +### Key Changes + + +# Impact + + +# Compatibility + + +# References (Optional) + + +# Additional Notes +- Do you have ideas regarding implementation? Yes / No +- Are you willing to implement this feature? Yes / No \ No newline at end of file diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 00000000000..9c3af93f787 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,56 @@ +name: "CodeQL" + +on: + push: + branches: [ 'develop', 'master', 'release_**' ] + pull_request: + # The branches below must be a subset of the branches above + branches: [ 'develop' ] + paths-ignore: [ '**/*.md', '.gitignore', '**/.gitignore', '.editorconfig', + '.gitattributes', 'docs/**', 'CHANGELOG', '.github/ISSUE_TEMPLATE/**', + '.github/PULL_REQUEST_TEMPLATE/**', '.github/CODEOWNERS' ] + schedule: + - cron: '6 10 * * 0' + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: [ 'java' ] + # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ] + # Use only 'java' to analyze code written in Java, Kotlin or both + # Use only 'javascript' to analyze code written in JavaScript, TypeScript or both + # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support + + steps: + - name: Checkout repository + uses: actions/checkout@v5 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: ${{ matrix.language }} + build-mode: manual + + - name: Set up JDK 8 + uses: actions/setup-java@v5 + with: + java-version: '8' + distribution: 'temurin' + + - name: Build + run: ./gradlew build -x test --no-daemon + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v4 + with: + category: "/language:${{matrix.language}}" diff --git a/.github/workflows/math-check.yml b/.github/workflows/math-check.yml new file mode 100644 index 00000000000..a5db3351a94 --- /dev/null +++ b/.github/workflows/math-check.yml @@ -0,0 +1,93 @@ +name: Check Math Usage + +on: + push: + branches: [ 'master', 'release_**' ] + pull_request: + branches: [ 'develop', 'release_**' ] + workflow_dispatch: + +jobs: + check-math: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v5 + + - name: Check for java.lang.Math usage + id: check-math + shell: bash + run: | + echo "Checking for java.lang.Math usage..." + + touch math_usage.txt + + while IFS= read -r file; do + filename=$(basename "$file") + if [[ "$filename" == "StrictMathWrapper.java" || "$filename" == "MathWrapper.java" ]]; then + continue + fi + + perl -0777 -ne ' + s/"([^"\\]|\\.)*"//g; + s/'\''([^'\''\\]|\\.)*'\''//g; + s!/\*([^*]|\*[^/])*\*/!!g; + s!//[^\n]*!!g; + $hasMath = 0; + $hasMath = 1 if /^[\s]*import[\s]+java\.lang\.Math\b/m; + $hasMath = 1 if /\bjava\s*\.\s*lang\s*\.\s*Math\s*\./; + $hasMath = 1 if /(?> math_usage.txt + done < <(find . -type f -name "*.java") + + sort -u math_usage.txt -o math_usage.txt + + if [ -s math_usage.txt ]; then + echo "❌ Error: Forbidden Math usage found in the following files:" + cat math_usage.txt + echo "math_found=true" >> $GITHUB_OUTPUT + echo "Please use org.tron.common.math.StrictMathWrapper instead of direct Math usage." + else + echo "✅ No forbidden Math usage found" + echo "math_found=false" >> $GITHUB_OUTPUT + fi + + - name: Upload findings + if: steps.check-math.outputs.math_found == 'true' + uses: actions/upload-artifact@v6 + with: + name: math-usage-report + path: math_usage.txt + + - name: Create comment + if: github.event_name == 'pull_request' && steps.check-math.outputs.math_found == 'true' + uses: actions/github-script@v8 + with: + script: | + const fs = require('fs'); + const findings = fs.readFileSync('math_usage.txt', 'utf8'); + const body = `### ❌ Math Usage Detection Results + + Found forbidden usage of \`java.lang.Math\` in the following files: + + \`\`\` + ${findings} + \`\`\` + + **Please review if this usage is intended.** + > [!CAUTION] + > Note: You should use \`org.tron.common.math.StrictMathWrapper\`. + > If you need to use \`java.lang.Math\`, please provide a justification. + `; + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: body + }); + + - name: Fail if Math usage found + if: steps.check-math.outputs.math_found == 'true' + run: exit 1 diff --git a/.github/workflows/pr-build.yml b/.github/workflows/pr-build.yml new file mode 100644 index 00000000000..dd005f98b74 --- /dev/null +++ b/.github/workflows/pr-build.yml @@ -0,0 +1,509 @@ +name: PR Build + +on: + pull_request: + branches: [ 'master','develop', 'release_**' ] + types: [ opened, synchronize, reopened ] + paths-ignore: [ '**/*.md', '.gitignore', '**/.gitignore', '.editorconfig', + '.gitattributes', 'docs/**', 'CHANGELOG', '.github/ISSUE_TEMPLATE/**', + '.github/PULL_REQUEST_TEMPLATE/**', '.github/CODEOWNERS' ] + workflow_dispatch: + inputs: + job: + description: 'Job to run: all / macos / ubuntu / rockylinux / debian11' + required: false + default: 'all' + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + + build-macos: + name: Build macos26 (JDK ${{ matrix.java }} / ${{ matrix.arch }}) + if: ${{ github.event_name == 'pull_request' || inputs.job == 'all' || inputs.job == 'macos' }} + runs-on: ${{ matrix.runner }} + timeout-minutes: 60 + strategy: + fail-fast: false + matrix: + include: + - java: '17' + runner: macos-26 + arch: aarch64 + + steps: + - uses: actions/checkout@v5 + + - name: Set up JDK ${{ matrix.java }} + uses: actions/setup-java@v5 + with: + java-version: ${{ matrix.java }} + distribution: 'temurin' + + - name: Cache Gradle packages + uses: actions/cache@v4 + with: + path: | + ~/.gradle/caches + ~/.gradle/wrapper + key: macos26-${{ matrix.arch }}-gradle-${{ hashFiles('**/*.gradle', '**/gradle-wrapper.properties') }} + restore-keys: macos26-${{ matrix.arch }}-gradle- + + - name: Build + run: ./gradlew clean build --no-daemon + + - name: Toolkit jar smoke test + run: | + set -e + JAR=plugins/build/libs/Toolkit.jar + java -jar "$JAR" help + java -jar "$JAR" db --help + java -jar "$JAR" db archive -h + java -jar "$JAR" keystore --help + + build-ubuntu: + name: Build ubuntu24 (JDK 17 / aarch64) + if: ${{ github.event_name == 'pull_request' || inputs.job == 'all' || inputs.job == 'ubuntu' }} + runs-on: ubuntu-24.04-arm + timeout-minutes: 60 + + steps: + - uses: actions/checkout@v5 + + - name: Set up JDK 17 + uses: actions/setup-java@v5 + with: + java-version: '17' + distribution: 'temurin' + + - name: Check Java version + run: java -version + + - name: Cache Gradle packages + uses: actions/cache@v4 + with: + path: | + ~/.gradle/caches + ~/.gradle/wrapper + key: ubuntu24-aarch64-gradle-${{ hashFiles('**/*.gradle', '**/gradle-wrapper.properties') }} + restore-keys: ubuntu24-aarch64-gradle- + + - name: Build + run: ./gradlew clean build --no-daemon + + - name: Toolkit jar smoke test + run: | + set -e + JAR=plugins/build/libs/Toolkit.jar + java -jar "$JAR" help + java -jar "$JAR" db --help + java -jar "$JAR" db archive -h + java -jar "$JAR" keystore --help + + docker-build-rockylinux: + name: Build rockylinux (JDK 8 / x86_64) + if: ${{ github.event_name == 'pull_request' || inputs.job == 'all' || inputs.job == 'rockylinux' }} + runs-on: ubuntu-latest + timeout-minutes: 60 + + container: + image: rockylinux:8 + + env: + GRADLE_USER_HOME: /github/home/.gradle + LANG: en_US.UTF-8 + LC_ALL: en_US.UTF-8 + + steps: + - name: Checkout code + uses: actions/checkout@v5 + + - name: Install dependencies (Rocky 8 + JDK8) + run: | + set -euxo pipefail + dnf -y install java-1.8.0-openjdk-devel git wget unzip which jq bc curl glibc-langpack-en + dnf -y groupinstall "Development Tools" + + - name: Check Java version + run: java -version + + - name: Cache Gradle + uses: actions/cache@v4 + with: + path: | + /github/home/.gradle/caches + /github/home/.gradle/wrapper + key: rockylinux-x86_64-gradle-${{ hashFiles('**/*.gradle', '**/gradle-wrapper.properties') }} + restore-keys: | + rockylinux-x86_64-gradle- + + - name: Stop Gradle daemon + run: ./gradlew --stop || true + + - name: Build + run: ./gradlew clean build --no-daemon + + - name: Toolkit jar smoke test + run: | + set -e + JAR=plugins/build/libs/Toolkit.jar + java -jar "$JAR" help + java -jar "$JAR" db --help + java -jar "$JAR" db archive -h + java -jar "$JAR" keystore --help + + - name: Test with RocksDB engine + run: ./gradlew :framework:testWithRocksDb --no-daemon + + docker-build-debian11: + name: Build debian11 (JDK 8 / x86_64) + if: ${{ github.event_name == 'pull_request' || inputs.job == 'all' || inputs.job == 'debian11' }} + runs-on: ubuntu-latest + timeout-minutes: 60 + + container: + image: eclipse-temurin:8-jdk # base image is Debian 11 (Bullseye) + + defaults: + run: + shell: bash + + env: + GRADLE_USER_HOME: /github/home/.gradle + + steps: + - name: Checkout code + uses: actions/checkout@v5 + + - name: Install dependencies (Debian + build tools) + run: | + set -euxo pipefail + apt-get update + apt-get install -y git wget unzip build-essential curl jq + + - name: Check Java version + run: java -version + + - name: Cache Gradle + uses: actions/cache@v4 + with: + path: | + /github/home/.gradle/caches + /github/home/.gradle/wrapper + key: debian11-x86_64-gradle-${{ hashFiles('**/*.gradle', '**/gradle-wrapper.properties') }} + restore-keys: | + debian11-x86_64-gradle- + + - name: Build + run: ./gradlew clean build --no-daemon --no-build-cache + + - name: Toolkit jar smoke test + run: | + set -e + JAR=plugins/build/libs/Toolkit.jar + java -jar "$JAR" help + java -jar "$JAR" db --help + java -jar "$JAR" db archive -h + java -jar "$JAR" keystore --help + + - name: Test with RocksDB engine + run: ./gradlew :framework:testWithRocksDb --no-daemon --no-build-cache + + - name: Generate module coverage reports + run: ./gradlew jacocoTestReport --no-daemon + + - name: Upload PR coverage reports + uses: actions/upload-artifact@v6 + with: + name: jacoco-coverage-pr + path: | + **/build/reports/jacoco/test/jacocoTestReport.xml + if-no-files-found: error + + coverage-base: + name: Coverage Base (JDK 8 / x86_64) + if: ${{ github.event_name == 'pull_request' }} + runs-on: ubuntu-latest + timeout-minutes: 60 + container: + image: eclipse-temurin:8-jdk # base image is Debian 11 (Bullseye) + defaults: + run: + shell: bash + env: + GRADLE_USER_HOME: /github/home/.gradle + permissions: + contents: read + + steps: + - name: Checkout code + uses: actions/checkout@v5 + with: + ref: ${{ github.event.pull_request.base.sha }} + + - name: Install dependencies (Debian + build tools) + run: | + set -euxo pipefail + apt-get update + apt-get install -y git wget unzip build-essential curl jq + + - name: Cache Gradle packages + uses: actions/cache@v4 + with: + path: | + /github/home/.gradle/caches + /github/home/.gradle/wrapper + key: coverage-base-x86_64-gradle-${{ hashFiles('**/*.gradle', '**/gradle-wrapper.properties') }} + restore-keys: | + coverage-base-x86_64-gradle- + + - name: Build (base) + run: ./gradlew clean build --no-daemon --no-build-cache + + - name: Test with RocksDB engine (base) + run: ./gradlew :framework:testWithRocksDb --no-daemon --no-build-cache + + - name: Generate module coverage reports (base) + run: ./gradlew jacocoTestReport --no-daemon + + - name: Upload base coverage reports + uses: actions/upload-artifact@v6 + with: + name: jacoco-coverage-base + path: | + **/build/reports/jacoco/test/jacocoTestReport.xml + if-no-files-found: error + + coverage-gate: + name: Coverage Gate + needs: [docker-build-debian11, coverage-base] + if: ${{ github.event_name == 'pull_request' }} + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + + steps: + - name: Checkout code + uses: actions/checkout@v5 + with: + fetch-depth: 0 + + - name: Download base coverage reports + uses: actions/download-artifact@v8 + with: + name: jacoco-coverage-base + path: coverage/base + + - name: Download PR coverage reports + uses: actions/download-artifact@v8 + with: + name: jacoco-coverage-pr + path: coverage/pr + + - name: Collect coverage report paths + id: collect-xml + run: | + BASE_XMLS=$(find coverage/base -name "jacocoTestReport.xml" | sort | paste -sd, -) + PR_XMLS=$(find coverage/pr -name "jacocoTestReport.xml" | sort | paste -sd, -) + if [ -z "$BASE_XMLS" ] || [ -z "$PR_XMLS" ]; then + echo "Missing jacocoTestReport.xml files for base or PR." + exit 1 + fi + echo "base_xmls=$BASE_XMLS" >> "$GITHUB_OUTPUT" + echo "pr_xmls=$PR_XMLS" >> "$GITHUB_OUTPUT" + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Changed-line coverage (diff-cover) + id: diff-cover + env: + BASE_REF: ${{ github.event.pull_request.base.ref }} + run: | + set -euo pipefail + pip install --quiet 'diff-cover==9.2.0' + + # Ensure the base branch ref is available locally for diff-cover. + git fetch --no-tags origin "+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}" + + PR_XMLS=$(find coverage/pr -name "jacocoTestReport.xml" | sort) + SRC_ROOTS=$(find . -type d -path '*/src/main/java' \ + -not -path './coverage/*' -not -path './.git/*' | sort) + if [ -z "$SRC_ROOTS" ]; then + echo "No src/main/java directories found; cannot run diff-cover." >&2 + exit 1 + fi + + set +e + diff-cover $PR_XMLS \ + --compare-branch="origin/${BASE_REF}" \ + --src-roots $SRC_ROOTS \ + --fail-under=0 \ + --json-report=diff-cover.json \ + --markdown-report=diff-cover.md + DIFF_RC=$? + set -e + + if [ ! -f diff-cover.json ]; then + echo "diff-cover did not produce JSON report (exit=${DIFF_RC})." >&2 + exit 1 + fi + + TOTAL_NUM_LINES=$(jq -r '.total_num_lines // 0' diff-cover.json) + if [ "${TOTAL_NUM_LINES}" = "0" ]; then + echo "No changed Java source lines; skipping changed-line gate." + echo "changed_line_coverage=NA" >> "$GITHUB_OUTPUT" + else + CHANGED_LINE_COVERAGE=$(jq -r '.total_percent_covered // empty' diff-cover.json) + if [ -z "$CHANGED_LINE_COVERAGE" ]; then + echo "Unable to parse changed-line coverage from diff-cover.json." + exit 1 + fi + echo "changed_line_coverage=${CHANGED_LINE_COVERAGE}" >> "$GITHUB_OUTPUT" + fi + + { + echo "### Changed-line Coverage (diff-cover)" + echo "" + if [ -f diff-cover.md ] && [ -s diff-cover.md ]; then + cat diff-cover.md + else + echo "_diff-cover produced no report._" + fi + } >> "$GITHUB_STEP_SUMMARY" + + - name: Aggregate base coverage + id: jacoco-base + uses: madrapps/jacoco-report@v1.7.2 + with: + paths: ${{ steps.collect-xml.outputs.base_xmls }} + token: ${{ secrets.GITHUB_TOKEN }} + min-coverage-overall: 0 + min-coverage-changed-files: 0 + skip-if-no-changes: true + comment-type: summary + title: '## Base Coverage Snapshot' + update-comment: false + + - name: Aggregate PR coverage + id: jacoco-pr + uses: madrapps/jacoco-report@v1.7.2 + with: + paths: ${{ steps.collect-xml.outputs.pr_xmls }} + token: ${{ secrets.GITHUB_TOKEN }} + min-coverage-overall: 0 + min-coverage-changed-files: 0 + skip-if-no-changes: true + comment-type: summary + title: '## PR Code Coverage Report' + update-comment: false + + - name: Enforce coverage gates + env: + BASE_OVERALL_RAW: ${{ steps.jacoco-base.outputs.coverage-overall }} + PR_OVERALL_RAW: ${{ steps.jacoco-pr.outputs.coverage-overall }} + CHANGED_LINE_RAW: ${{ steps.diff-cover.outputs.changed_line_coverage }} + run: | + set -euo pipefail + + MIN_CHANGED=60 + MAX_DROP=-0.1 + + sanitize() { + echo "$1" | tr -d ' %' + } + is_number() { + [[ "$1" =~ ^-?[0-9]+([.][0-9]+)?$ ]] + } + compare_float() { + # Usage: compare_float "" + # Example: compare_float "1.2 >= -0.1" + awk "BEGIN { if ($1) print 1; else print 0 }" + } + + # 1) Parse metrics from jacoco-report outputs + BASE_OVERALL="$(sanitize "$BASE_OVERALL_RAW")" + PR_OVERALL="$(sanitize "$PR_OVERALL_RAW")" + CHANGED_LINE="$(sanitize "$CHANGED_LINE_RAW")" + + if ! is_number "$BASE_OVERALL" || ! is_number "$PR_OVERALL"; then + echo "Failed to parse coverage values: base='${BASE_OVERALL}', pr='${PR_OVERALL}'." + exit 1 + fi + + # 2) Compare metrics against thresholds + DELTA=$(awk -v pr="$PR_OVERALL" -v base="$BASE_OVERALL" 'BEGIN { printf "%.4f", pr - base }') + DELTA_OK=$(compare_float "${DELTA} >= ${MAX_DROP}") + + if [ "$CHANGED_LINE" = "NA" ]; then + CHANGED_LINE_OK=1 + CHANGED_LINE_STATUS="SKIPPED (no changed Java source lines)" + elif [ -z "$CHANGED_LINE" ] || [ "$CHANGED_LINE" = "NaN" ] || ! is_number "$CHANGED_LINE"; then + echo "Failed to parse changed-line coverage: changed-line='${CHANGED_LINE}'." + exit 1 + else + CHANGED_LINE_OK=$(compare_float "${CHANGED_LINE} > ${MIN_CHANGED}") + if [ "$CHANGED_LINE_OK" -eq 1 ]; then + CHANGED_LINE_STATUS="PASS (> ${MIN_CHANGED}%)" + else + CHANGED_LINE_STATUS="FAIL (<= ${MIN_CHANGED}%)" + fi + fi + + # 3) Output base metrics (always visible in logs + step summary) + OVERALL_STATUS="PASS (>= ${MAX_DROP}%)" + if [ "$DELTA_OK" -ne 1 ]; then + OVERALL_STATUS="FAIL (< ${MAX_DROP}%)" + fi + + if [ "$CHANGED_LINE" = "NA" ]; then + CHANGED_LINE_DISPLAY="NA" + else + CHANGED_LINE_DISPLAY="${CHANGED_LINE}%" + fi + + METRICS_TEXT=$(cat <> "$GITHUB_STEP_SUMMARY" + + # 4) Decide CI pass/fail + if [ "$DELTA_OK" -ne 1 ]; then + echo "Coverage gate failed: overall coverage dropped more than 0.1%." + echo "base=${BASE_OVERALL}% pr=${PR_OVERALL}% delta=${DELTA}%" + exit 1 + fi + + if [ "$CHANGED_LINE_OK" -ne 1 ]; then + echo "Coverage gate failed: changed-line coverage must be > 60%." + echo "changed-line=${CHANGED_LINE}%" + exit 1 + fi + + echo "Coverage gates passed." diff --git a/.github/workflows/pr-cancel.yml b/.github/workflows/pr-cancel.yml new file mode 100644 index 00000000000..bbd0e68c235 --- /dev/null +++ b/.github/workflows/pr-cancel.yml @@ -0,0 +1,55 @@ +name: Cancel PR Workflows on Close + +on: + pull_request: + types: [ closed ] + +permissions: + actions: write + +jobs: + cancel: + name: Cancel In-Progress Workflows + if: github.event.pull_request.merged == false + runs-on: ubuntu-latest + steps: + - name: Cancel PR Build and System Test + uses: actions/github-script@v8 + with: + script: | + const workflows = ['pr-build.yml', 'system-test.yml', 'codeql.yml']; + const headSha = context.payload.pull_request.head.sha; + const prNumber = context.payload.pull_request.number; + + for (const workflowId of workflows) { + for (const status of ['in_progress', 'queued']) { + const runs = await github.paginate( + github.rest.actions.listWorkflowRuns, + { + owner: context.repo.owner, + repo: context.repo.repo, + workflow_id: workflowId, + status, + event: 'pull_request', + per_page: 100, + }, + (response) => response.data.workflow_runs + ); + + for (const run of runs) { + if (!run) { + continue; + } + const prs = Array.isArray(run.pull_requests) ? run.pull_requests : []; + const isTargetPr = prs.length === 0 || prs.some((pr) => pr.number === prNumber); + if (run.head_sha === headSha && isTargetPr) { + await github.rest.actions.cancelWorkflowRun({ + owner: context.repo.owner, + repo: context.repo.repo, + run_id: run.id, + }); + console.log(`Cancelled ${workflowId} run #${run.id} (${status})`); + } + } + } + } diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml new file mode 100644 index 00000000000..19425209bbc --- /dev/null +++ b/.github/workflows/pr-check.yml @@ -0,0 +1,131 @@ +name: PR Check + +on: + push: + branches: [ 'master', 'release_**' ] + pull_request: + branches: [ 'develop', 'release_**' ] + types: [ opened, edited, synchronize, reopened ] + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.ref }} + cancel-in-progress: true + +jobs: + pr-lint: + name: PR Lint + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + + steps: + - name: Validate PR title and description + uses: actions/github-script@v8 + with: + script: | + const title = context.payload.pull_request.title; + const body = context.payload.pull_request.body; + const errors = []; + const warnings = []; + + const allowedTypes = ['feat','fix','refactor','docs','style','test','chore','ci','perf','build','revert']; + const knownScopes = [ + 'framework','chainbase','actuator','consensus','common','crypto','plugins','protocol', + 'net','db','vm','tvm','api','jsonrpc','rpc','http','event','config', + 'block','proposal','trie','log','metrics','test','docker','version', + 'freezeV2','DynamicEnergy','stable-coin','reward','lite','toolkit' + ]; + + // 1. Title length check + if (!title || title.trim().length < 10) { + errors.push('PR title is too short (minimum 10 characters).'); + } + if (title && title.length > 72) { + errors.push(`PR title is too long (${title.length}/72 characters).`); + } + + // 2. Conventional format check + const conventionalRegex = /^(feat|fix|refactor|docs|style|test|chore|ci|perf|build|revert)(\([^)]+\))?:\s\S.*/; + if (title && !conventionalRegex.test(title)) { + errors.push( + 'PR title must follow conventional format: `type(scope): description`\n' + + ' Allowed types: ' + allowedTypes.map(t => `\`${t}\``).join(', ') + '\n' + + ' Example: `feat(tvm): add blob opcodes`' + ); + } + + // 3. No trailing period + if (title && title.endsWith('.')) { + errors.push('PR title should not end with a period (.).'); + } + + // 4. Description part should not start with a capital letter + if (title) { + const descMatch = title.match(/^\w+(?:\([^)]+\))?:\s*(.+)/); + if (descMatch) { + const desc = descMatch[1]; + if (/^[A-Z]/.test(desc)) { + errors.push('Description should not start with a capital letter.'); + } + } + } + + // 5. Scope validation (warning only) + if (title) { + const scopeMatch = title.match(/^\w+\(([^)]+)\):/); + if (scopeMatch && !knownScopes.includes(scopeMatch[1])) { + warnings.push(`Unknown scope \`${scopeMatch[1]}\`. See CONTRIBUTING.md for known scopes.`); + } + } + + // 6. PR description check + if (!body || body.trim().length < 20) { + errors.push('PR description is too short or empty (minimum 20 characters). Please describe what this PR does and why.'); + } + + // Output warnings + for (const w of warnings) { + core.warning(w); + } + + // Output result + if (errors.length > 0) { + const docLink = 'See [CONTRIBUTING.md](https://github.com/' + context.repo.owner + '/' + context.repo.repo + '/blob/develop/CONTRIBUTING.md#pull-request-guidelines) for details.'; + const message = '### PR Lint Failed\n\n' + errors.map(e => `- ${e}`).join('\n') + '\n\n' + docLink; + core.setFailed(message); + } else { + core.info('PR lint passed.'); + } + + checkstyle: + name: Checkstyle + runs-on: ubuntu-24.04-arm + + steps: + - uses: actions/checkout@v5 + + - name: Set up JDK 17 + uses: actions/setup-java@v5 + with: + java-version: '17' + distribution: 'temurin' + + - name: Cache Gradle packages + uses: actions/cache@v4 + with: + path: | + ~/.gradle/caches + ~/.gradle/wrapper + key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle', '**/gradle-wrapper.properties') }} + restore-keys: ${{ runner.os }}-gradle- + + - name: Run Checkstyle + run: ./gradlew :framework:checkstyleMain :framework:checkstyleTest :plugins:checkstyleMain + + - name: Upload Checkstyle reports + if: failure() + uses: actions/upload-artifact@v6 + with: + name: checkstyle-reports + path: | + framework/build/reports/checkstyle/ + plugins/build/reports/checkstyle/ diff --git a/.github/workflows/pr-reviewer.yml b/.github/workflows/pr-reviewer.yml new file mode 100644 index 00000000000..bf124acf576 --- /dev/null +++ b/.github/workflows/pr-reviewer.yml @@ -0,0 +1,144 @@ +name: Auto Assign Reviewers + +on: + pull_request_target: + branches: [ 'develop', 'release_**' ] + types: [ opened, edited, reopened ] + +jobs: + assign-reviewers: + name: Assign Reviewers by Scope + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + + steps: + - name: Assign reviewers based on PR title scope + uses: actions/github-script@v8 + with: + script: | + const title = context.payload.pull_request.title; + const prAuthor = context.payload.pull_request.user.login; + + // ── Scope → Reviewer mapping ────────────────────────────── + const scopeReviewers = { + 'framework': ['xxo1shine', '317787106'], + 'chainbase': ['halibobo1205', 'lvs0075'], + 'db': ['halibobo1205', 'xxo1shine'], + 'trie': ['halibobo1205', '317787106'], + 'actuator': ['yanghang8612', 'lxcmyf'], + 'consensus': ['lvs0075', 'xxo1shine'], + 'protocol': ['lvs0075', 'waynercheung'], + 'common': ['xxo1shine', 'lxcmyf'], + 'crypto': ['Federico2014', '3for'], + 'net': ['317787106', 'xxo1shine'], + 'vm': ['yanghang8612', 'CodeNinjaEvan'], + 'tvm': ['yanghang8612', 'CodeNinjaEvan'], + 'jsonrpc': ['0xbigapple', 'bladehan1'], + 'rpc': ['317787106', 'Sunny6889'], + 'http': ['Sunny6889', 'bladehan1'], + 'event': ['xxo1shine', '0xbigapple'], + 'config': ['317787106', 'halibobo1205'], + 'backup': ['xxo1shine', '317787106'], + 'lite': ['bladehan1', 'halibobo1205'], + 'toolkit': ['halibobo1205', 'Sunny6889'], + 'plugins': ['halibobo1205', 'Sunny6889'], + 'docker': ['3for', 'kuny0707'], + 'test': ['bladehan1', 'lxcmyf'], + 'metrics': ['halibobo1205', 'Sunny6889'], + 'api': ['0xbigapple', 'waynercheung', 'bladehan1'], + 'ci': ['bladehan1', 'halibobo1205'], + }; + const defaultReviewers = ['halibobo1205', '317787106']; + + // ── Normalize helper ───────────────────────────────────── + // Strip spaces, hyphens, underscores and lower-case so that + // "VM", " json rpc ", "chain-base", "Json_Rpc" all normalize + // to their canonical key form ("vm", "jsonrpc", "chainbase"). + const normalize = s => s.toLowerCase().replace(/[\s\-_]/g, ''); + + // ── Extract scope from conventional commit title ────────── + // Format: type(scope): description + // Also supports: type(scope1,scope2): description + const scopeMatch = title.match(/^\w+\(([^)]+)\):/); + const rawScope = scopeMatch ? scopeMatch[1] : null; + + core.info(`PR title : ${title}`); + core.info(`Raw scope: ${rawScope || '(none)'}`); + + // ── Skip if reviewers already assigned ────────────────── + const pr = await github.rest.pulls.get({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.payload.pull_request.number, + }); + const existing = pr.data.requested_reviewers || []; + if (existing.length > 0) { + core.info(`Reviewers already assigned (${existing.map(r => r.login).join(', ')}). Skipping.`); + return; + } + + // ── Determine reviewers ─────────────────────────────────── + // 1. Split by comma to support multi-scope: feat(vm,rpc): ... + // 2. Normalize each scope token + // 3. Match against keys: exact match first, then contains match + // (longest key wins to avoid "net" matching inside "jsonrpc") + let matched = new Set(); + let matchedScopes = []; + + if (rawScope) { + const tokens = rawScope.split(',').map(s => normalize(s.trim())); + // Pre-sort keys by length descending so longer keys match first + const sortedKeys = Object.keys(scopeReviewers) + .sort((a, b) => b.length - a.length); + + for (const token of tokens) { + if (!token) continue; + // Exact match + if (scopeReviewers[token]) { + matchedScopes.push(token); + scopeReviewers[token].forEach(r => matched.add(r)); + continue; + } + // Contains match: token contains a key, or key contains token + // Prefer longest key that matches + const found = sortedKeys.find(k => token.includes(k) || k.includes(token)); + if (found) { + matchedScopes.push(`${token}→${found}`); + scopeReviewers[found].forEach(r => matched.add(r)); + } + } + } + + let reviewers = matched.size > 0 + ? [...matched] + : defaultReviewers; + + core.info(`Matched scopes: ${matchedScopes.length > 0 ? matchedScopes.join(', ') : '(none — using default)'}`); + core.info(`Candidate reviewers: ${reviewers.join(', ')}`); + + // Exclude the PR author from the reviewer list + reviewers = reviewers.filter(r => r.toLowerCase() !== prAuthor.toLowerCase()); + + if (reviewers.length === 0) { + core.info('No eligible reviewers after excluding PR author. Skipping.'); + return; + } + + core.info(`Assigning reviewers: ${reviewers.join(', ')}`); + + // ── Request reviews ─────────────────────────────────────── + try { + await github.rest.pulls.requestReviewers({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.payload.pull_request.number, + reviewers: reviewers, + }); + core.info('Reviewers assigned successfully.'); + } catch (error) { + // If a reviewer is not a collaborator the API returns 422; + // log the error but do not fail the workflow. + core.warning(`Failed to assign some reviewers: ${error.message}`); + } diff --git a/.github/workflows/system-test.yml b/.github/workflows/system-test.yml new file mode 100644 index 00000000000..f6184fb0efc --- /dev/null +++ b/.github/workflows/system-test.yml @@ -0,0 +1,95 @@ +name: System Test + +on: + push: + branches: [ 'master', 'release_**' ] + pull_request: + branches: [ 'develop', 'release_**' ] + types: [ opened, synchronize, reopened ] + paths-ignore: [ '**/*.md', '.gitignore', '**/.gitignore', '.editorconfig', + '.gitattributes', 'docs/**', 'CHANGELOG', '.github/ISSUE_TEMPLATE/**', + '.github/PULL_REQUEST_TEMPLATE/**', '.github/CODEOWNERS' ] + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + system-test: + name: System Test (JDK 8 / x86_64) + runs-on: ubuntu-latest + timeout-minutes: 60 + + steps: + - name: Set up JDK 8 + uses: actions/setup-java@v5 + with: + java-version: '8' + distribution: 'temurin' + + - name: Clone system-test + uses: actions/checkout@v5 + with: + repository: tronprotocol/system-test + ref: release_workflow + path: system-test + + - name: Checkout java-tron + uses: actions/checkout@v5 + with: + path: java-tron + + - name: Cache Gradle packages + uses: actions/cache@v4 + with: + path: | + ~/.gradle/caches + ~/.gradle/wrapper + key: ${{ runner.os }}-gradle-system-test-${{ hashFiles('java-tron/**/*.gradle', 'java-tron/**/gradle-wrapper.properties') }} + restore-keys: ${{ runner.os }}-gradle-system-test- + + - name: Build java-tron + working-directory: java-tron + run: ./gradlew clean build -x test --no-daemon + + - name: Copy config and start FullNode + run: | + cp system-test/testcase/src/test/resources/config-system-test.conf java-tron/ + cd java-tron + nohup java -jar build/libs/FullNode.jar --witness -c config-system-test.conf > fullnode.log 2>&1 & + echo "FullNode started, waiting for it to be ready..." + + MAX_ATTEMPTS=60 + INTERVAL=5 + for i in $(seq 1 $MAX_ATTEMPTS); do + if curl -s --fail "http://localhost:8090/wallet/getblockbynum?num=1" > /dev/null 2>&1; then + echo "FullNode is ready! (attempt $i)" + exit 0 + fi + echo "Waiting... (attempt $i/$MAX_ATTEMPTS)" + sleep $INTERVAL + done + + echo "FullNode failed to start within $((MAX_ATTEMPTS * INTERVAL)) seconds." + echo "=== FullNode log (last 50 lines) ===" + tail -50 fullnode.log || true + exit 1 + + - name: Run system tests + working-directory: system-test + run: | + if [ ! -f solcDIR/solc-linux-0.8.6 ]; then + echo "ERROR: solc binary not found at solcDIR/solc-linux-0.8.6" + exit 1 + fi + cp solcDIR/solc-linux-0.8.6 solcDIR/solc + ./gradlew clean --no-daemon + ./gradlew --info stest --no-daemon + + - name: Upload FullNode log + if: always() + uses: actions/upload-artifact@v6 + with: + name: fullnode-log + path: java-tron/fullnode.log + if-no-files-found: warn diff --git a/.gitignore b/.gitignore index b980800f353..3917bb44679 100644 --- a/.gitignore +++ b/.gitignore @@ -31,7 +31,6 @@ shareddata.* # protobuf generated classes src/main/gen - src/main/java/org/tron/core/bftconsensus src/test/java/org/tron/consensus2 src/main/java/META-INF/ @@ -55,3 +54,6 @@ Wallet # vm_trace /vm_trace/ + +/framework/propPath +.cache diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 7a3b00d2ece..00000000000 --- a/.travis.yml +++ /dev/null @@ -1,45 +0,0 @@ -sudo: required -dist: trusty -language: java -dist: trusty -jdk: oraclejdk8 -addons: - ssh_known_hosts: - - 47.93.42.145:22008 - - 47.93.42.145:22008 - - 47.93.42.145:22008 - - 47.93.18.60:22008 - - 47.93.18.60:22008 - - 47.93.18.60:22008 - sonarcloud: - organization: tron-zhaohong - token: - secure: "KXWEeQ1elAoQ0XfR54TQWfhrIdDP0+2CYPv2X9aWpU/YDl7hqZBAjcCOAUGvlbyM54jtG6YMaWwG48jlrOwwl5l/VjWSnUXF+7ixQy5ki0Ci9s7Y1pTQwV9SpL8TLIK2TYqabN8Mw+FJULASXLjYr9GerbbcUbCPTmcL6mQKw6ivxxpNPmz4eNoKAEuOzruO9fTXGAV3yr8Nn85c+mVxV8EUhkR17zpE9O8fvzOtSnYArWNOSCgDBn0EG45UNNPF2vn44s1c3h3gX1m3WK6PeCXPgy3hPqRn3wTG+xglnbqthGpo2wt1rJ83af+BwdYwvPEcUq84yLgXcE/aMkTKcVAfPWBP/6vblaoI90jxCeFji+MdMimKZAqIXt7oLqDZVmIq65de5YC5s7QTSbzJNY/tsAu3dqzSfbUJY6CRNFDcoenVpvgQkqb37TkDah4mJM8EUjbu2A9Q2HSFbyCVsQJtdasuu9cBOf6azK3U0XgFNBc0y2aziZrTnX30q7bi+5L/mbTnRdXrDqBOqyPeGtT77UZfcajHHmEWU/e6gYWiA/c+K25n13DD53Au6gpnnQ6ALeUl/1gDwz3fPBebJ5bVWrkIcLj7bbysjzfOvQmDS6G13RNz58Hm0/B7bVtZTr1E1q6Z1zEJwbuJYEJASNcezAfK5x/hIfZTGNqT3M8=" -cache: - directories: - - '$HOME/.sonar/cache' -matrix: - include: - - name: build - script: - - sh tron.sh - - "./gradlew build" - - "./gradlew jacocoTestReport" - - - - name: stest - script: - - sh tron.sh - - bash deploy.sh - - -after_success: - - "bash <(curl -s https://codecov.io/bash)" - -skip_build: - - README.md： - - LICENSE - - - - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e2830a2473..ef67a81e3ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,83 +1,348 @@ # Contributing to java-tron -java-tron is an open source project. +java-tron is an open-source project which needs the support of open-source contributors. -It is the work of contributors. We appreciate your help! +Below are the instructions. We understand that there is much left to be desired, and if you see any room for improvement, please let us know. Thank you. -Here are instructions to get you started. They are not perfect, so -please let us know if anything feels wrong or incomplete. +Here are some guidelines to get started quickly and easily: +- [Reporting An Issue](#Reporting-An-Issue) +- [Working on java-tron](#Working-on-java-tron) + - [Key Branches](#Key-Branches) + - [Submitting Code](#Submitting-Code) +- [Code Review Guidelines](#Code-Review-Guidelines) + - [Terminology](#Terminology) + - [The Process](#The-Process) + - [Code Style](#Code-Style) + - [Commit Messages](#Commit-Messages) + - [Branch Naming Conventions](#Branch-Naming-Conventions) + - [Pull Request Guidelines](#Pull-Request-Guidelines) + - [PR Title Format](#PR-Title-Format) + - [Type and Scope Reference](#Type-and-Scope-Reference) + - [PR Description](#PR-Description) + - [Special Situations And How To Deal With Them](#Special-Situations-And-How-To-Deal-With-Them) +- [Conduct](#Conduct) -## Contribution guidelines -First of all, java-tron follows GitFlow, the branches description in the java-tron project are listed as follow: -``master`` branch: -This branch contains the latest code released to the production environment. It can only be merged, and can not be modified directly in this branch. +## Reporting An Issue -``develop`` branch: -This branch is the main development branch. It contains the complete code that is going to release. It can only be merged, and can not be modified directly in this branch. +If you have any question about java-tron, please search [existing issues](https://github.com/tronprotocol/java-tron/issues?q=is%3Aissue%20state%3Aclosed%20OR%20state%3Aopen) first to avoid duplicates. Your questions might already be under discussion or part of our roadmap. Checking first helps us streamline efforts and focus on new contributions. -``feature`` branch: -This branch is used to develop new features. It is created based on ``develop`` branch. Once the development is finished, it should be merged into ``develop`` branch, and then delete the branch. +### Ask a question +Feel free to ask any java-tron related question to solve your doubt. Please click **Ask a question** in GitHub Issues, using [Ask a question](.github/ISSUE_TEMPLATE/ask-a-question.md) template. -``release`` branch: -This is the branch that is going to be released. It is created based on ``develop`` branch. In this branch, small fix and modification of final version of metadata is allowed. When the code is released, this branch should be merged into ``master`` branch(tag needed) and ``develop`` branch. The final test before release uses this branch. +### Report a bug -``hotfix`` branch: -This branch is used to fix a bug when an online bug is found. It is created based on ``master`` branch. When bug fix is done, it should be merged into ``master`` branch(as a new release) and ``develop`` and then delete the branch. branch. +If you think you've found a bug with java-tron, please click **Report a bug** in GitHub Issues, using [Report a bug](.github/ISSUE_TEMPLATE/report-a-bug.md) template. -### Pull requests +### Request a feature -If you'd like to contribute to java-tron, you should follow the steps below: -- **Fork** a repository from **tronprotocol/java-tron** allows you to freely experiment with changes without affecting the original project -- **Fix** some code and **Commit** your modified code. -- **Send** a Pull Request（PR）for the maintainers to review and merge into the main code base. - *notice*：When you create a new PR，please choose the **tronprotocol/java-tron** as the base repository and choose **your fork/java-tron** as the head repository. - And you must choose **develop** as the base repository branch, which means we will merge the PR into our **develop** branch when reviewed and approved. - Additionally, if you are writing a new feature, please ensure you add appropriate test cases under ``/src/test``. +If you have any good feature suggestions for java-tron, please click **Request a feature** in GitHub Issues, using [Request a feature](.github/ISSUE_TEMPLATE/request-a-feature.md) template. -After the PR is checked by our Sonar check procedure and Travis CI continuous-integration check procedure automaticly, -we maintainers will review the code changed and give some advices for modifying if necessary.Once approved, -we will close the PR and merge into the protocol/java-tron's develop branch. -We are always happy to receive pull requests, and do our best to -review them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We would appreciate it. +## Working on java-tron +Thank you for considering to help out with the source code! We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes! -If your pull request is not accepted on the first try, don't be -discouraged as it can be a possible oversight. Please explain your code as -detailed as possible to make it easier for us to understand. +If you’d like to contribute to java-tron, for small fixes, we recommend that you send a pull request (PR) for the maintainers to review and merge into the main code base, make sure the PR contains a detailed description. For more complex changes, you need to submit an issue to the TIP repository to detail your motive and implementation plan, etc. For how to submit a TIP issue, please refer to [TIP Specification](https://github.com/tronprotocol/tips#to-submit-a-tip). -Please make sure your contributions adhere to our coding guidelines: -- Code must be documented adhering to the [Google Style](https://google.github.io/styleguide/javaguide.html) -- Code must pass Sonar detection. -- Pull requests need to be based on and opened against the develop branch. -- Commit messages should be started with verb, and the first letter should be a lowercase.The length of commit message -must be limited in 50 words. -### Create issues +As the author of TIP issue, you are expected to encourage developers to discuss this issue, flesh out your issue by collecting their feedback, and eventually put your issue into practice. -Any significant improvement should be documented as [a GitHub -issue](https://github.com/tronprotocol/java-tron/issues) before anyone -starts working on it. -When filing an issue, make sure to answer these three questions: +### Key Branches +java-tron only has `master`, `develop`, `release-*`, `feature-*`, and `hotfix-*` branches, which are described below: -- What did you do? -- What did you expect to see? -- What did you see instead? +- ``develop`` branch + The `develop` branch only accept merge request from other forked branches or`release_*` branches. It is not allowed to directly push changes to the `develop` branch. A `release_*` branch has to be pulled from the develop branch when a new build is to be released. -### Please check existing issues and docs first! +- ``master`` branch + `release_*` branches and `hotfix/*` branches should only be merged into the `master` branch when a new build is released. -Please take a moment to check that your bug report or improvement proposal -doesn't already exist. If it does, please add a quick "+1" or "I have this problem too". -This will help prioritize the most common problems and requests. +- ``release`` branch + `release_*` is a branch pulled from the `develop` branch for release. It should be merged into `master` after a regression test and will be permanently kept in the repository. If a bug is identified in a `release_*` branch, its fixes should be directly merged into the branch. After passing the regression test, the `release_*` branch should be merged back into the `develop` branch. Essentially, a `release_*` branch serves as a snapshot for each release. -## Community Developers Incentives Programme +- ``feature`` branch + `feature/*` is an important feature branch pulled from the `develop` branch. After the `feature/*` branch is code-complete, it should be merged back to the `develop` branch. The `feature/*` branch is maintainable. -Bonus point applies in TRON incentives programme. Developers can earn points by contributing to TRON. +- ``hotfix`` branch + It is pulled from the `master` branch and should be merged back into the master branch and the `develop` branch. Only pull requests of the fork repository (pull requests for bug fixes) should be merged into the `hotfix/` branch. `hotfix/` branches are used only for fixing bugs found after release. -You can find your points ranking at [Tronscan](https://tronscan.org/#/developersreward). -The Top 5 scored developers (for every month, quarter and year) can win a cash reward. +### Submitting Code -For more details, please visit [Incentives Policy](https://tronprotocol.github.io/documentation-en/developers/incentives/). +If you want to contribute code to java-tron, please follow the following steps. + +* Fork the Repository + + Visit [tronprotocol/java-tron](https://github.com/tronprotocol/java-tron/) and click **Fork** to create a fork repository under your GitHub account. + +* Setup Local Environment + + Clone your fork repository to local and add the official repository as **upstream**. + ``` + git clone https://github.com/yourname/java-tron.git + + cd java-tron + + git remote add upstream https://github.com/tronprotocol/java-tron.git + ``` + +* Synchronize and Develop + + Before developing new features, please synchronize your local `develop` branch with the upstream repository and update to your fork repository. + ``` + git fetch upstream + git checkout develop + # `--no-ff` means to turn off the default fast merge mode + git merge upstream/develop --no-ff + git push origin develop + ``` + + Create a new branch for development. Please refer to [Branch Naming Conventions](#Branch-Naming-Conventions). + ``` + git checkout -b feature/branch_name develop + ``` + +* Commit and Push + + Write and commit the new code when it is completed. Please refer to [Commit Messages](#Commit-Messages). + ``` + git add . + git commit -m 'commit message' + ``` + + Push the new branch to your fork repository + ``` + git push origin feature/branch_name + ``` + +* Submit a pull request + + Submit a pull request (PR) from your fork repository to `tronprotocol/java-tron`. + Please be sure to click on the link in the red box shown below. Select the base branch for `tronprotocol/java-tron` and the compare branch for your fork repository. + ![image](https://raw.githubusercontent.com/tronprotocol/documentation-en/master/images/javatron_pr.png) + + + +## Code Review Guidelines +The only way to get code into java-tron is to send a pull request. Those pull requests need to be reviewed by someone. The following guide explains our expectations around PRs for both authors and reviewers. + +### Terminology +- The author of a pull request is the entity who wrote the diff and submitted it to GitHub. +- The team consists of people with commit rights on the java-tron repository. +- The reviewer is the person assigned to review the diff. The reviewer must be a team member. +- The code owner is the person responsible for the subsystem being modified by the PR. + +### The Process +The first decision to make for any PR is whether it’s worth including at all. This decision lies primarily with the code owner, but may be negotiated with team members. + +To make the decision we must understand what the PR is about. If there isn’t enough description content or the diff is too large, request an explanation. Anyone can do this part. + +We expect that reviewers check the style and functionality of the PR, providing comments to the author using the GitHub review system. Reviewers should follow up with the PR until it is in good shape, then approve the PR. Approved PRs can be merged by any code owner. + +When communicating with authors, be polite and respectful. + +### Code Style +We would like all developers to follow a standard development flow and coding style. Therefore, we suggest the following: +1. Review the code with coding style checkers. +2. Review the code before submission. +3. Run standardized tests. + +`Sonar`-scanner and CI checks (GitHub Actions) will be automatically triggered when a pull request has been submitted. When a PR passes all the checks, the **java-tron** maintainers will then review the PR and offer feedback and modifications when necessary. Once adopted, the PR will be closed and merged into the `develop` branch. + +We are glad to receive your pull requests and will try our best to review them as soon as we can. Any pull request is welcome, even if it is for a typo. + +Please kindly address the issue you find. We would appreciate your contribution. + +Please do not be discouraged if your pull request is not accepted, as it may be an oversight. Please explain your code as detailed as possible to make it easier to understand. + +Please make sure your submission meets the following code style: + +- The code must conform to [Google Code Style](https://google.github.io/styleguide/javaguide.html). +- The code must have passed the Sonar scanner test. +- The code has to be pulled from the `develop` branch. +- The commit message should start with a verb, whose initial should not be capitalized. +- The commit message title should be between 10 and 72 characters in length. + + + +### Commit Messages + +Commit messages should follow the rule below, we provide a template with corresponding instructions. + +Template: +``` +(): + + + +