Skip to content

Latest commit

 

History

History
146 lines (116 loc) · 6.83 KB

CONTRIBUTING.md

File metadata and controls

146 lines (116 loc) · 6.83 KB
Raw

Contributing

This document provides guidelines for contributing to Amoro. While these suggestions are not strict rules, they aim to facilitate a smooth contribution experience.

Issues

Regardless of the type of contribution you plan to make, it is recommended that you create an issue to track it.

  • Before creating an issue, please search within the issues to see if a similar one has already been reported.
  • Choose the appropriate type:
    • Feature: A new feature to be added.
    • Improvement: Enhancement of an existing feature, including code quality, performance, user experience, etc.
    • Bug: A problem that prevents the project from functioning as intended.
    • Subtask: A subtask of a Feature/Improvement that can be broken down into smaller steps.

Pull requests

Pull requests are the preferred mechanism for contributing to Amoro

  • Generally, create a PR only to the master branch.
  • PR should be linked to the corresponding issue.
    • The PR title format should be: [AMORO-{issue_number}][{module}]{pr_description}.
    • Add fix/resolve #{issue_number} in the description to link the PR to the issue.
    • The linked issue should clearly explain the background, objectives, and implementation methods of the PR.
  • The change log in the PR should clearly describe the changes made in modules, classes, methods, etc.
  • The PR should include corresponding testing methods, and the test results should be visible.
  • If the PR involves new features, the user document should include instructions for its usage.

Code review

Code review is a crucial aspect of contributing to a project, and all contributors are encouraged to actively review and provide feedback on each other's PRs.

  • Check whether the PR meet the requirements specified in the previous section on Pull Requests.
  • Review each file changed by the PR, and consider the following aspects:
    • Is the java doc complete?
    • Is there new unit or integration test coverage for the code changes?
    • Does the user document explain how to use new features?
    • Are there comments to aid in understanding complex logic?
    • Have any duplicate classes or methods been introduced?
  • Track feedback on suggestions and their resolution.
  • If a suggestion is resolved, please close it.
  • If all suggestions are resolved or there are no suggestions, approve it.

Design document

Write down your implementation plan and discuss it with other developers in the community before you start coding officially. If it is just a small change, describe the implementation steps clearly in the Issue. If it is a relatively large work, it is recommended to write a design document for this feature. Here is a design document template for reference.

Building the Project Locally

Build Guide can be found in GitHub readme.

Code suggestions

Code formatting

Amoro uses Spotless together with google-java-format to format the Java code. For Scala, it uses Spotless with scalafmt.

You can format your code by executing the command mvn spotless:apply in the root directory of project.

Or you can configure your IDEA to automatically format your code. Then you will need to install the google-java-format plugin. However, a specific version of this plugin is required. Download google-java-format v1.7.0.6 and install it as follows. Make sure to never update this plugin.

  1. Go to “Settings/Preferences” → “Plugins”.
  2. Click the gear icon and select “Install Plugin from Disk”.
  3. Navigate to the downloaded ZIP file and select it.

After installing the plugin, format your code automatically by applying the following settings:

  1. Go to “Settings/Preferences” → “Other Settings” → “google-java-format Settings”.
  2. Tick the checkbox to enable the plugin.
  3. Change the code style to “Default Google Java style”.
  4. Go to “Settings/Preferences” → Editor → Code Style → Scala.
  5. Change the “Formatter” to “scalafmt”.
  6. Go to “Settings/Preferences” → “Tools” → “Actions on Save”.
  7. Under “Formatting Actions”, select “Optimize imports” and “Reformat file”.
  8. From the “All file types list” next to “Reformat code”, select Java and Scala.

Copyright

All files (including source code, configuration files) in the project are required to declare CopyRight information at the top, and the project uses Apache License 2. You can configure the copyright information in IntelliJ IDEA with the following steps:

  1. Open Settings → Editor → Copyright → Copyright Profiles.
  2. Add a new copyright file named Apache.
  3. Add the following text as the license text:
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and 
limitations under the License.
  1. Go to Editor → Copyright and select the Apache copyright file as the default copyright file for the project.
  2. Click Apply to save the configuration changes.
  3. Right-click on the existing File/Package/Module and select Update Copyrights… to update the Copyright of the file.