6.3 Community Contributions

• 1: 6.3.1 Local Development Testing
• 2: 6.3.2 Completing the First PR Submission
• 3: 6.3.3 Document, Issue, and Process Contribution
• 4: 6.3.4 Organizing Meetings and Promoting Operations

1 - 6.3.1 Local Development Testing

SOFAArk and Arklet

SOFAArk is a regular Java SDK project that uses Maven as its dependency management and build tool. You only need to install Maven 3.6 or higher locally to develop code and run unit tests normally, without any other environment preparation.
For details on code submission, please refer to: Completing the First PR Submission.

ModuleController

ModuleController is a standard K8S Golang Operator component, which includes ModuleDeployment Operator, ModuleReplicaSet Operator, and Module Operator. You can use minikube for local development testing. For details, please refer to Local Quick Start.
To compile and build, execute the following command in the module-controller directory:

go mod download   # if compile module-controller first time
go build -a -o manager cmd/main.go  

To run unit tests, execute the following command in the module-controller directory:

make test

You can also use an IDE for compiling, building, debugging, and running unit tests.
The development approach for module-controller is exactly the same as the standard K8S Operator development approach. You can refer to the official K8S Operator development documentation。

Arkctl

Arkctl is a regular Golang project, which is a command-line toolset that includes common tools for users to develop and maintain modules locally. You can refer here

2 - 6.3.2 Completing the First PR Submission

Claim or Submit an Issue

Regardless of whether you’re fixing a bug, adding a new feature, or improving an existing one, before you submit your code, please claim an issue on Koupleless or SOFAArk GitHub and assign yourself as the Assignee (novices are encouraged to claim tasks tagged with good-first-issue). Alternatively, submit a new issue describing the problem you want to fix or the feature you want to add or improve. Doing so helps avoid duplicate work with others.

Obtaining the Source Code

To modify or add features, after claiming or taking an existing issue, click the fork button in the upper left corner to make a copy of Koupleless or SOFAArk’s mainline code to your code repository.

Creating a Branch

All modifications to Koupleless and SOFAArk are made on individual branches. After forking the source code, you need to:

• Download the code to your local machine, either via git/https:

git clone https://github.com/your-username/koupleless.git

git clone https://github.com/your-username/sofa-ark.git

• Create a branch to prepare for modifying the code:

git branch add_xxx_feature

After executing the above command, your code repository will switch to the respective branch. You can verify your current branch by executing the following command:

  git branch -a

If you want to switch back to the mainline, execute the following command:

  git checkout -b master

If you want to switch back to a branch, execute the following command:

  git checkout -b "branchName"

Modifying and Submitting Code Locally

After creating a branch, you can start modifying the code.

Things to Consider When Modifying Code

• Maintain consistent code style. Koupleless arklet and sofa-ark use Maven plugins to ensure consistent code formatting. Before submitting the code, make sure to execute:

mvn clean compile

The formatting capability for module-controller and arkctl’s Golang code is still under development.

• Include supplementary unit test code.
• Ensure that new modifications pass all unit tests.
• If it’s a bug fix, provide new unit tests to demonstrate that the previous code had bugs and that the new code fixes them. For arklet and sofa-ark, you can run all tests with the following command:

mvn clean test

For module-controller and arkctl, you can run all tests with the following command:

make test

You can also use an IDE to assist.

Other Considerations

• Please keep the code you edit in the original style, especially spaces, line breaks, etc.
• Delete unnecessary comments. Comments must be in English.
• Add comments to logic and functionalities that are not easily understood.
• Ensure to update the relevant documents in the docs/content/zh-cn/ directory, specifically in the docs and contribution-guidelines directories.

After modifying the code, commit all changes to your local repository using the following command:

git commit -am 'Add xx feature'

Submitting Code to Remote Repository

After committing the code locally, it’s time to synchronize the code with the remote repository. Submit your local modifications to GitHub with the following command:

git push origin "branchname"

If you used fork earlier, then here “origin” pushes to your code repository, not Koupleless’s repository.

Requesting to Merge Code into Main Branch

After submitting the code to GitHub, you can request to merge your well-improved code into Koupleless’s or SOFAArk’s mainline code. At this point, you need to go to your GitHub repository and click the pull request button in the upper right corner. Select the target branch, usually master, and the Maintainer or PMC of the corresponding component as the Code Reviewer. If the PR pipeline check and Code Review are both successful, your code will be merged into the mainline and become a part of Koupleless.

PR Pipeline Check

The PR pipeline check includes:

1. CLA signing. The first time you submit a PR, you must sign the CLA agreement. If you cannot open the CLA signing page, try using a proxy.
2. Automatic appending of Apache 2.0 License declaration and author to each file.
3. Execution of all unit tests, and all must pass.
4. Checking if the coverage rate reaches line coverage >= 80% and branch coverage >= 60%.
5. Detecting if the submitted code has security vulnerabilities.
6. Checking if the submitted code complies with basic code standards.

All the above checks must pass for the PR pipeline to pass and enter the Code Review stage.

Code Review

If you choose the Maintainer or PMC of the corresponding component as the Code Reviewer, and after several days, there is still no response to your submission, you can leave a message below the PR and mention the relevant people, or directly mention them in the community DingTalk collaboration group (DingTalk group ID: 24970018417) to review the code. The comments on the Code Review will be directly noted in the corresponding PR or Issue. If you find the suggestions reasonable, please update your code accordingly and resubmit the PR.

Merging Code into Main Branch

After the PR pipeline check and Code Review are both successful, Koupleless maintainers will merge the code into the mainline. After the code is merged, you will receive a notification of successful merging.

3 - 6.3.3 Document, Issue, and Process Contribution

Documentation Contribution

Maintaining user documentation, technical documentation, and website content is a collective effort of every contributor in the community. Any student who contributes to any document or website content is considered a contributor, and based on their activity, they may have the opportunity to become a Committer or even a PMC member of Koupleless, jointly leading the technical evolution of Koupleless.

Issue Submission and Response Contribution

Any issues, bugs, new features, or improvements encountered during usage should be reported via GitHub Issues. Community members take turns each day to follow up on issues. Anyone who raises or responds to issues is a contributor to Koupleless. Contributors who actively respond to issues may be promoted to Committer status, and exceptionally active contributors may even be promoted to PMC members, jointly leading the technical evolution of Koupleless.

Issue Templates

There are two templates for Koupleless (including SOFAArk) Issues: “Question or Bug Report” and “Feature Request”.

Question or Bug Report

For any issues encountered during usage or suspected bugs, please select “Question or Bug Report” and provide detailed replication information as follows:

### Describe the question or bug

A clear and concise description of what the question or bug is.

### Expected behavior

A clear and concise description of what you expected to happen.

### Actual behavior

A clear and concise description of what actually happened.

### Steps to reproduce

Steps to reproduce the problem:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

### Screenshots

If applicable, add screenshots to help explain your problem.

### Minimal yet complete reproducer code (or GitHub URL to code)

### Environment

- SOFAArk version:
- JVM version (e.g. `java -version`):
- OS version (e.g. `uname -a`):
- Maven version:
- IDE version:

Feature Request

For new features, improvements to existing features, or other discussions, please select “Feature Request”.

Process Contribution

Currently, Koupleless has established various collaboration standards such as code conventions, PR processes, CI pipelines, iteration management, weekly meetings, and communication channels. You can suggest improvements to our collaboration standards and processes on GitHub to become our contributor.

4 - 6.3.4 Organizing Meetings and Promoting Operations

We encourage everyone to promote and advocate for Koupleless, and through operations, become Koupleless contributors, committers, and even PMC members. Each promotion of a contributor will also be rewarded with commemorative prizes. Operation methods include but are not limited to:

1. Delivering speeches on the use or technical implementation of Koupleless at online or offline technical conferences and meetups.
2. Sharing and exchanging Koupleless usage scenarios with other companies.
3. Publishing articles or videos related to the use or technical implementation of Koupleless on various channels.
4. Other operational methods.