Apex Contributing Guidelines

• Apex Contributing Guidelines
  • Contributor License Agreement
  • Getting Started
  • Development Guidance
  • Code Style
  • Gate Exception Handling
  • Fork-Pull Development Model
  • Reporting Issues
  • Proposing PRs

Contributor License Agreement

You must sign a Contributor License Agreement (CLA) before your first code submission to the Ascend community.

For individual contributors, please refer to the ICLA online document for details.

Getting Started

• Fork the repository on GitCode.
• Read the README.en.md for project information and build instructions.
• Read the Code of Conduct.

Development Guidance

• Code Style
• Gate Exception Handling
• Fork-Pull Development Model
• Reporting Issues
• Proposing PRs

Code Style

Please follow these guidelines to make Apex easy to develop, review, and maintain.

• Coding guidelines

  Please use the unified coding style in the Ascend community. The recommended Python coding style is PEP 8 Coding Style, and the recommended C++ coding style is Google C++ Coding Guidelines. You can use CppLint, CppCheck, CMakeLint, CodeSpell, Lizard, ShellCheck, and PyLint to check code formatting. Installing these plugins in your IDE is recommended.

• Unit test (UT) guidelines

  Please use the unified UT style in the Ascend community. The recommended Python UT style is pytest, and the recommended C++ UT style is Googletest Primer. The design intent of a test case should be reflected in its name or comment.

• Refactoring guidelines

  We encourage developers to refactor our code to eliminate code smell. All code should meet the coding style and testing style requirements, and refactoring code is no exception. When you receive a warning, you must refactor the code you want to merge.

Gate Exception Handling

Gate exceptions mainly include the following types. Please resolve each issue according to the relevant guidance.

• Build failure

  Check why the code failed to build. For common build issues, see GitCode issues, or open an issue to share your idea.

• Static analysis failure, including code bugs, code vulnerabilities, and code smells

  Follow the prompt to locate and fix the issue in the code.

• UT failure

  Follow the prompt to identify the failing test case, check the cause, and run the tests again after you fix it.

Fork-Pull Development Model

1. Fork the Apex repository.

   Before submitting code to the Apex project, please make sure that this project has been forked to your own repository. This means there will be parallel development between the Apex repository and your own repository. Therefore, be careful to avoid inconsistencies between them.

2. Clone the remote repository.

   If you want to download the code to your local environment, git is a good choice:

   # For GitCode
   git clone https://gitcode.com/{insert_your_forked_repo}/apex.git
   git remote add upstream https://gitcode.com/Ascend/apex.git
   

3. Develop code locally.

   To avoid inconsistencies between branches, you are advised to check out a new branch:

   git checkout -b {new_branch_name} origin/master
   

   Using the master branch as an example, Apex may create version branches and downstream development branches as needed. Please fix upstream bugs first. Then you can modify the code as needed.

4. Push the code to the remote repository.

   After updating the code, you should push the update in the following way:

   git add .
   git status # Check the update status
   git commit -m "Your commit title"
   git commit -s --amend
   # Commit the code to your branch
   git push origin {new_branch_name}
   

5. Submit a pull request (PR) to the Apex repository.

   In the final step, you need to submit a PR between your new branch and the Apex master branch. After the PR is submitted, Jenkins CI will be configured automatically to run the build tests. Your PR should be merged into the upstream master branch as soon as possible to reduce merge risk.

Reporting Issues

A good way to contribute to the project is to send a detailed report when you encounter an issue. We always appreciate a well-written, thorough bug report, and we will thank you for it.

When reporting issues, refer to this format:

• What version of the environment (Apex, OS, Python, and so on) are you using?
• Is this a bug report or a feature request?
• What kind of issue is it? Add labels to highlight it on the issue dashboard.
• What happened?
• What did you expect to happen?
• How do you reproduce it? (As minimally and precisely as possible.)
• Special notes for your reviewers?

Issue guidance:

• If you find an open issue that is exactly what you plan to solve, please comment on that issue to let others know that you will take it on.
• If an issue has been open for a while, you are advised to do a preliminary check before you start working on it.
• If you resolve an issue that you reported yourself, you also need to let others know before closing it.

Proposing PRs

• Raise your idea as an issue on GitCode.
• If it is a new feature that requires many design details, a design proposal should also be submitted.
• After reaching consensus in the issue discussions and design proposal reviews, complete the development on the forked repository and submit a PR.
• Any PR requires at least two LGTM from approvers. Please note that approvers are not allowed to add LGTM on their own PR.
• After a PR is fully discussed, it will be merged, abandoned, or rejected depending on the outcome of the discussion.

PR guidance:

• Avoid any unrelated changes.
• Ensure that your commit history is in order.
• Always keep your branch in sync with the master branch.
• For bug-fix PRs, make sure all related issues are linked.