From b50d95927ffe97ac5e3c7b3afe6dcaf48f281238 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Thu, 26 Feb 2026 16:11:44 +0800 Subject: [PATCH 1/4] fix readme typo and format --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 0f8b30704b..c8c4cbeeda 100644 --- a/README.md +++ b/README.md @@ -31,14 +31,14 @@ TRON is building the foundational infrastructure for the decentralized internet ecosystem with a focus on high-performance, scalability, and security. -- TRON Protocol: High-throughput（2000+ TPS), scalable blockchain OS (DPoS consensus) powering the TRON ecosystem. +- TRON Protocol: High-throughput (2000+ TPS), scalable blockchain OS (DPoS consensus) powering the TRON ecosystem. - TRON Virtual Machine (TVM): EVM-compatible smart-contract engine for fast smart-contract execution. # Building the Source Code Before building java-tron, make sure you have: - Hardware with at least 4 CPU cores, 16 GB RAM, 10 GB free disk space for a smooth compilation process. - Operating system: `Linux` or `macOS` (`Windows` is not supported). -- Git and correct JDK（version `8` or `17`） installed based on your CPU architecture. +- Git and correct JDK (version `8` or `17`) installed based on your CPU architecture. There are two ways to install the required dependencies: @@ -128,7 +128,7 @@ tail -f ./logs/tron.log Use [TronScan](https://tronscan.org/#/), TRON's official block explorer, to view main network transactions, blocks, accounts, witness voting, and governance metrics, etc. ### 2. Join Nile test network -Utilize the `-c` flag to direct the node to the configuration file corresponding to the desired network. Since Nile TestNet may incorporate features not yet available on the MainNet, it is **strongly advised** to compile the source code following the [Building the Source Code](https://github.com/tron-nile-testnet/nile-testnet/blob/master/README.md#building-the-source-code) instructions for the Nile TestNet. +Utilize the `-c` flag to direct the node to the configuration file corresponding to the desired network. Since Nile Testnet may incorporate features not yet available on the Mainnet, it is **strongly advised** to compile the source code following the [Building the Source Code](https://github.com/tron-nile-testnet/nile-testnet/blob/master/README.md#building-the-source-code) instructions for the Nile Testnet. ```bash java -jar ./build/libs/FullNode.jar -c config-nile.conf @@ -139,7 +139,7 @@ Nile resources: explorer, faucet, wallet, developer docs, and network statistics ### 3. Access Shasta test network Shasta does not accept public node peers. Programmatic access is available via TronGrid endpoints; see [TronGrid Service](https://developers.tron.network/docs/trongrid) for details. -Shasta resources: explorer, faucet, wallet, developer docs, and network statistics at [shastaex.io](https://shasta.tronex.io/). +Shasta resources: explorer, faucet, wallet, developer docs, and network statistics at [shasta.tronex.io](https://shasta.tronex.io/). ### 4. Set up a private network To set up a private network for testing or development, follow the [Private Network guidance](https://tronprotocol.github.io/documentation-en/using_javatron/private_network/). @@ -160,7 +160,7 @@ You could also test the process by connecting to a testnet or setting up a priva ## Programmatically interfacing FullNode -Upon the FullNode startup successfully, interaction with the TRON network is facilitated through a comprehensive suite of programmatic interfaces exposed by java-tron: +Once the FullNode starts successfully, interaction with the TRON network is facilitated through a comprehensive suite of programmatic interfaces exposed by java-tron: - **HTTP API**: See the complete [HTTP API reference and endpoint list](https://tronprotocol.github.io/documentation-en/api/http/). - **gRPC**: High-performance APIs suitable for service-to-service integration. See the supported [gRPC reference](https://tronprotocol.github.io/documentation-en/api/rpc/). - **JSON-RPC**: Provides Ethereum-compatible JSON-RPC methods for logs, transactions and contract calls, etc. See the supported [JSON-RPC methods](https://tronprotocol.github.io/documentation-en/api/json-rpc/). @@ -201,14 +201,14 @@ Thank you for considering to help out with the source code! If you'd like to con # Resources -- [Medium](https://medium.com/@coredevs) java-tron's official technical articles are published there. +- [Medium](https://medium.com/@coredevs) - java-tron's official technical articles are published here. - [Documentation](https://tronprotocol.github.io/documentation-en/) and [TRON Developer Hub](https://developers.tron.network/) serve as java-tron’s primary documentation websites. -- [TronScan](https://tronscan.org/#/) TRON main network blockchain browser. -- [Nile Test network](http://nileex.io/) A stable test network of TRON contributed by TRON community. -- [Shasta Test network](https://shasta.tronex.io/) A stable test network of TRON contributed by TRON community. -- [Wallet-cli](https://github.com/tronprotocol/wallet-cli) TRON network wallet using command line. -- [TIP](https://github.com/tronprotocol/tips) TRON Improvement Proposal (TIP) describes standards for the TRON network. -- [TP](https://github.com/tronprotocol/tips/tree/master/tp) TRON Protocol (TP) describes standards already implemented in TRON network but not published as a TIP. +- [TronScan](https://tronscan.org/#/) - TRON main network blockchain browser. +- [Nile Test Network](https://nileex.io/) - A stable test network of TRON contributed by the TRON community. +- [Shasta Test Network](https://shasta.tronex.io/) - A stable test network of TRON contributed by the TRON community. +- [Wallet-cli](https://github.com/tronprotocol/wallet-cli) - TRON network wallet using command line. +- [TIP](https://github.com/tronprotocol/tips) - TRON Improvement Proposal (TIP) describes standards for the TRON network. +- [TP](https://github.com/tronprotocol/tips/tree/master/tp) - TRON Protocol (TP) describes standards already implemented in TRON network but not published as a TIP. # Integrity Check From e387f72e9c381d425679562023d76d7782904c5b Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 27 Feb 2026 15:52:16 +0800 Subject: [PATCH 2/4] revert change (+1 squashed commit) Squashed commits: [f7b03afa84] update CONTRIBUTING.md and clear up the directory --- CONTRIBUTING.md | 327 +++++++++++++++++++++++++++--------------------- 1 file changed, 185 insertions(+), 142 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79bf8567a6..0da38289b0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,159 +1,190 @@ # Contributing to java-tron -java-tron is an open-source project which needs the support of open-source contributors. +Thank you for considering contributing to java-tron! We welcome contributions from anyone and are grateful for even the smallest fixes. -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. +java-tron is an open-source project that thrives on community support. This guide will help you contribute effectively. If you have suggestions for improving this guide, please let us know. -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) - - [Special Situations And How To Deal With Them](#Special-Situations-And-How-To-Deal-With-Them) -- [Conduct](#Conduct) +## Table of Contents +- [Reporting An Issue](#reporting-an-issue) +- [Working on java-tron](#working-on-java-tron) + - [Contribution Types](#contribution-types) + - [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) + - [Special Situations](#special-situations-and-how-to-deal-with-them) +- [Code of Conduct](#code-of-conduct) -### Reporting An Issue +## Reporting An Issue -If you're about to raise an issue because you think you've found a problem or bug with java-tron, please respect the following restrictions: +Before raising an issue, please follow these guidelines: -- Please search for existing issues. Help us keep duplicate issues to a minimum by checking to see if someone has already reported your problem or requested your idea. +- **Search for existing issues** - Help us avoid duplicates by checking if someone has already reported your problem or requested your feature. -- Use the Issue Report Template below. +- **Use the Issue Report Template** - Provide clear information using this format: ``` - 1.What did you do? + 1. What did you do? - 2.What did you expect to see? + 2. What did you expect to see? - 3.What did you see instead? + 3. What did you see instead? ``` - ## 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 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). +### Contribution Types -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. +**For small fixes:** +- Submit a pull request (PR) directly with a detailed description +- Maintainers will review and merge into the main codebase +**For complex changes:** +- Submit a TIP (TRON Improvement Proposal) issue first +- Detail your motivation and implementation plan +- Refer to the [TIP Specification](https://github.com/tronprotocol/tips#to-submit-a-tip) for submission guidelines ### Key Branches -java-tron only has `master`, `develop`, `release-*`, `feature-*`, and `hotfix-*` branches, which are described below: -- ``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. +java-tron uses the following branch structure: -- ``master`` branch - `release_*` branches and `hotfix/*` branches should only be merged into the `master` branch when a new build is released. +- **`develop` branch** + - Accepts merge requests from forked branches or `release_*` branches only + - Direct pushes are not allowed + - Source branch for creating new `release_*` branches -- ``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. +- **`master` branch** + - Receives merges from `release_*` and `hotfix/*` branches only + - Updated only when a new build is released + - Represents the production-ready state -- ``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. +- **`release_*` branch** + - Created from `develop` for each release + - Merged into `master` after passing regression tests + - Permanently kept in the repository as a release snapshot + - Bug fixes can be applied directly to this branch + - After regression tests, merged back into `develop` -- ``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. +- **`feature/*` branch** + - Created from `develop` for new feature development + - Merged back to `develop` when code-complete + - Maintained throughout the feature development lifecycle +- **`hotfix/*` branch** + - Created from `master` for urgent production bug fixes + - Merged back into both `master` and `develop` branches + - Used exclusively for fixing critical bugs found after release + - Only accepts pull requests for bug fixes from forked repositories ### Submitting Code -If you want to contribute codes to java-tron, please follow the following steps: +Follow these steps to contribute code to java-tron: -* Fork code repository - Fork a new repository from tronprotocol/java-tron to your personal code repository +**1. Fork the repository** + - Fork tronprotocol/java-tron to your personal GitHub account -* Edit the code in the fork repository - ``` +**2. Clone and configure your fork** + ```bash git clone https://github.com/yourname/java-tron.git - - git remote add upstream https://github.com/tronprotocol/java-tron.git ("upstream" refers to upstream projects repositories, namely tronprotocol's repositories, and can be named as you like it. We usually call it "upstream" for convenience) - ``` - Before developing new features, please synchronize your fork repository with the upstream repository. - ``` - git fetch upstream - git checkout develop - git merge upstream/develop --no-ff (Add --no-ff to turn off the default fast merge mode) + git remote add upstream https://github.com/tronprotocol/java-tron.git ``` - Pull a new branch from the develop branch of your repository for local development. Please refer to [Branch Naming Conventions](#Branch-Naming-Conventions), +**3. Synchronize with upstream** + Before developing, sync your fork with the upstream repository: + ```bash + git fetch upstream + git checkout develop + git merge upstream/develop --no-ff # Disable fast-forward merge ``` + +**4. Create a feature branch** + Create a new branch from `develop` (see [Branch Naming Conventions](#branch-naming-conventions)): + ```bash git checkout -b feature/branch_name develop ``` - Write and commit the new code when it is completed. Please refer to [Commit Messages](#Commit-Messages) - ``` - git add . - git commit -m 'commit message' - ``` - Commit the new branch to your personal remote repository - ``` - git push origin feature/branch_name - ``` - -* Push code - - Submit a pull request (PR) from your 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 and the compare branch for your personal fork repository. - ![image](https://raw.githubusercontent.com/tronprotocol/documentation-en/master/images/javatron_pr.png) +**5. Develop and commit** + Write your code and commit changes (see [Commit Messages](#commit-messages)): + ```bash + git add . + git commit -m 'commit message' + ``` +**6. Push to your fork** + ```bash + git push origin feature/branch_name + ``` +**7. Create a pull request** + - Submit a PR from your fork to `tronprotocol/java-tron` + - Select the appropriate base branch (usually `develop`) + - Select your feature branch as the compare branch + - ![PR Guide](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. + +All code changes must go through the pull request review process. This section outlines expectations for both PR 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. + +- **Author**: The entity who wrote the diff and submitted it to GitHub +- **Team**: People with commit rights on the java-tron repository +- **Reviewer**: The person assigned to review the diff (must be a team member) +- **Code owner**: The person responsible for the subsystem being modified ### 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. +**Initial Assessment:** +- Code owners evaluate PR inclusion based on adequate descriptions and reasonable diff sizes +- Anyone can request clarification when needed -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. +**Review Responsibilities:** +- Reviewers verify code style and functionality +- Provide constructive feedback through GitHub's review system +- Maintain professional communication throughout the process +- Follow up until quality standards are met +- Approve when ready for merge -When communicating with authors, be polite and respectful. +**Merging:** +- Code owners merge approved PRs ### 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 `Travis CI` continuous integration scanner 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. +**Before Submitting:** +1. Use coding style checkers to review your code +2. Perform a self-review before submission +3. Run all standardized tests -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. +**Automated Checks:** +- Sonar scanner and Travis CI run automatically on all PRs +- PRs must pass all checks before maintainer review -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 should be less than 50 characters in length. +**Review Process:** +- Maintainers provide feedback and request modifications as needed +- Approved PRs are merged into the `develop` branch +- All contributions are welcome, including typo fixes +**If Your PR is Not Accepted:** +- Don't be discouraged - it may be an oversight +- Provide detailed explanations to help reviewers understand your changes +- Address feedback constructively +**Code Style Requirements:** +- Code must conform to [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) +- Code must pass Sonar scanner tests +- Branches must be created from `develop` +- Commit messages must start with a lowercase verb +- Commit subject lines must be 50 characters or less ### Commit Messages -Commit messages should follow the rule below, we provide a template with corresponding instructions. +Follow this template for all commit messages: -Template: ``` (): @@ -162,9 +193,10 @@ Template: