diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000000..0da38289b07 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,288 @@ +# Contributing to java-tron + +Thank you for considering contributing to java-tron! We welcome contributions from anyone and are grateful for even the smallest fixes. + +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. + +## 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 + +Before raising an issue, please follow these guidelines: + +- **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** - Provide clear information using this format: + ``` + 1. What did you do? + + 2. What did you expect to see? + + 3. What did you see instead? + ``` + +## Working on java-tron + +### Contribution Types + +**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 uses the following branch structure: + +- **`develop` branch** + - Accepts merge requests from forked branches or `release_*` branches only + - Direct pushes are not allowed + - Source branch for creating new `release_*` branches + +- **`master` branch** + - Receives merges from `release_*` and `hotfix/*` branches only + - Updated only when a new build is released + - Represents the production-ready state + +- **`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` + +- **`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 + +Follow these steps to contribute code to java-tron: + +**1. Fork the repository** + - Fork tronprotocol/java-tron to your personal GitHub account + +**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 + ``` + +**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 + ``` + +**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 + +All code changes must go through the pull request review process. This section outlines expectations for both PR authors and reviewers. + +### Terminology + +- **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 + +**Initial Assessment:** +- Code owners evaluate PR inclusion based on adequate descriptions and reasonable diff sizes +- Anyone can request clarification when needed + +**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 + +**Merging:** +- Code owners merge approved PRs + +### Code Style + +**Before Submitting:** +1. Use coding style checkers to review your code +2. Perform a self-review before submission +3. Run all standardized tests + +**Automated Checks:** +- Sonar scanner and Travis CI run automatically on all PRs +- PRs must pass all checks before maintainer review + +**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 + +Follow this template for all commit messages: + +``` +(): + + + +