diff --git a/.github/ISSUE_TEMPLATE/ask-a-question.md b/.github/ISSUE_TEMPLATE/ask-a-question.md index e503998b477..f785d28610f 100644 --- a/.github/ISSUE_TEMPLATE/ask-a-question.md +++ b/.github/ISSUE_TEMPLATE/ask-a-question.md @@ -1,10 +1,54 @@ --- name: Ask a question -about: Something is unclear -title: '' +about: Something is unclear or needs clarification +title: '[QUESTION] ' labels: 'type:docs' assignees: '' --- -This should only be used in very rare cases e.g. if you are not 100% sure if something is a bug or asking a question that leads to improving the documentation. For general questions please use [Discord](https://discord.gg/cGKSsRVCGm) or [Telegram](https://t.me/TronOfficialDevelopersGroupEn). + + + +## Question + +[Clearly describe what you need clarification on] + +## Context + +[Provide relevant context that helps us understand your question] + +**What are you trying to achieve?** + +[Describe your goal or use case] + +**What have you tried so far?** + +[List any approaches or solutions you've attempted] + +**Relevant documentation or code** + +[Link to relevant documentation, code sections, or examples] + +## Environment (if applicable) + +- Java-tron version: [e.g., 4.7.4] +- Operating System: [e.g., Ubuntu 20.04] +- Java version: [e.g., OpenJDK 1.8.0_161] + +## Additional Information + +[Any other details that might be helpful] diff --git a/.github/ISSUE_TEMPLATE/report-a-bug.md b/.github/ISSUE_TEMPLATE/report-a-bug.md index a0d68121565..a08e60b97cb 100644 --- a/.github/ISSUE_TEMPLATE/report-a-bug.md +++ b/.github/ISSUE_TEMPLATE/report-a-bug.md @@ -1,50 +1,88 @@ --- name: Report a bug about: Create a report to help us improve -title: '' +title: '[BUG] ' labels: 'type:bug' assignees: '' --- - - - + -#### Software Versions - +## Bug Description + +[Provide a clear and concise description of the bug] + +## Environment + +**Software Versions** + +Run `java -jar FullNode.jar -v` to get version information: - -#### Expected behaviour - +**Configuration** + +[If relevant, describe your node configuration (e.g., FullNode, SolidityNode, witness settings)] + +## Expected Behavior + +[Describe what you expected to happen] + +## Actual Behavior +[Describe what actually happened] + +## 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] +``` -#### Actual behaviour - +## Additional Context +[Add any other context about the problem] -#### Frequency - +**Screenshots** -#### Steps to reproduce the behaviour +[If applicable, add screenshots to help explain the problem] -1. [Step 1] -2. [Step 2] -3. [Step ...] +**Related Issues** -#### Backtrace +[Link to any related issues or pull requests] -```` -[backtrace] -```` +**Possible Solution** -When submitting logs: please submit them as text and not screenshots. +[If you have suggestions on how to fix the bug, describe them here] diff --git a/.github/ISSUE_TEMPLATE/request-a-feature.md b/.github/ISSUE_TEMPLATE/request-a-feature.md index 261f1088ded..f638d777cdd 100644 --- a/.github/ISSUE_TEMPLATE/request-a-feature.md +++ b/.github/ISSUE_TEMPLATE/request-a-feature.md @@ -1,28 +1,130 @@ --- name: Request a feature about: Suggest an idea for this project -title: '' +title: '[FEATURE] ' labels: 'type:feature' assignees: '' --- -# Background -# Rationale + -Why should this feature exist? +## Background -What are the use-cases? +[Describe the context and motivation for this feature request] -# Specification +## Problem Statement -# Test Specification +[What problem does this feature solve? What pain points does it address?] -# Scope Of Impact +## Rationale +**Why should this feature exist?** -# Implementation +[Explain the benefits and value this feature would provide] -Do you have ideas regarding the implementation of this feature? +**What are the use cases?** -Are you willing to implement this feature? +[Describe specific scenarios where this feature would be useful] + +1. +2. +3. + +**Who would benefit from this feature?** + +[e.g., node operators, developers, end users, validators] + +## Proposed Solution + +[Describe your proposed solution in detail] + +### Specification + +[Provide technical specifications or requirements] + +**API Changes** (if applicable) + +[Describe any new or modified APIs] + +**Configuration Changes** (if applicable) + +[Describe any new configuration options] + +**Protocol Changes** (if applicable) + +[Describe any changes to the TRON protocol] + +## Testing Strategy + +[How should this feature be tested?] + +**Test Scenarios** +1. +2. +3. + +**Performance Considerations** + +[Describe any performance implications] + +## Scope of Impact + +[What parts of the system will be affected?] + +- [ ] Core protocol +- [ ] API/RPC +- [ ] Database +- [ ] Network layer +- [ ] Smart contracts +- [ ] Documentation +- [ ] Other: [specify] + +**Breaking Changes** + +[Will this feature introduce any breaking changes?] + +**Backward Compatibility** + +[How will this feature maintain backward compatibility?] + +## Implementation + +**Do you have ideas regarding the implementation?** + +[Share any technical approaches or implementation details] + +**Are you willing to implement this feature?** + +[Let us know if you'd like to contribute the implementation] +- [ ] Yes, I can implement this feature +- [ ] I can help with implementation +- [ ] I need help with implementation +- [ ] I'm just suggesting the idea + +**Estimated Complexity** + +[Your assessment of implementation complexity] +- [ ] Low (minor changes) +- [ ] Medium (moderate changes) +- [ ] High (significant changes) +- [ ] Unknown + +## Alternatives Considered + +[Describe any alternative solutions or features you've considered] + +## Additional Context + +[Add any other context, mockups, diagrams, or examples] + +**Related Issues/PRs** + +[Link to any related issues or pull requests] + +**References** + +[Link to any relevant documentation, specifications, or discussions] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79bf8567a61..ef2abed8d3c 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: