Hi, Community For the orchestration unit test task we just released, in order to help new contributors join in faster, we have provided a unit test development guide.
New contributors can complete the development from setting up the development environment to completing a unit test of orchestration with the help of the guide. Also available at ISSUE[1]. . [1] https://github.com/apache/incubator-shardingsphere/issues/4438 Guide content: Welcome to Apache ShardingSphere! Here are some tips for new contributors. Prepare the environment Apache ShardingSphere is based on the Java platform, so you need related environment tools: -JDK8 version, -Java development tool IDE, IDEA or Eclipse is recommended, install lombok plugin -Git, or git integrated in the IDE -Maven3.5 If running Sharding-Proxy locally, you also need: -MySQL 5.6 or 5.7 server. If you want to verify PostGreSQL or other database related functions, you need to install the corresponding database software. -Zookeeper 3.5.6 or other version. If you want to verify the configuration center of Apollo or Nacos, you need to install the corresponding software. If you want to debug and run UI related projects, you need to install: -Node 8.11.1 or higher and corresponding NPM 5.6.0 or higher. Project instructionDownload source code Project address: https://github.com/apache/incubator-shardingsphere Source code description The source code includes the following sections: -Main project: SQL Engine, Sharding-jdbc, Sharding-proxy, Orchestration, etc. -ShardingSphere-UI: frontend (NodeJS / VUE), backend (Java) -doc project: Documentation, which is also the official website. Need to use Go-based Hugo tools to compile to static content. -examples project: use examples. Branch description We advocate modifying and committing on a dedicated branch, and finally request a merge to the trunk through a pull request (PR). Currently, the backbone of apache / incubator-shardingsphere is master and the version is 5.0.0-RC [N] -SNAPSHOT. There is also a 4.0.1 branch that is under maintenance 4.x. The latest version currently released is 4.0.0 (note that it is not 4.0.0-RC3). The entire official website and documentation are based on this version. A new branch of doc5.x was newly pulled in order to rewrite 5.x documentation and generate a new version of the website. Improve the unit test work, you can directly PR to the master. Clone project First, you need to add a star to the project by clicking star on the top right corner on github. Then, click fork, which will generate a new copy of your id path. For example, mine is: https://github.com/kimmking/incubator-shardingsphere Download source At present, if you git clone the entire project from github, it is about 240M, (because you want to download all the commit records). You can use the following methods to reduce the first download data to 20M: git clone https://github.com/{your id} / incubator-shardingsphere --depth 1 This will only keep the last 2 commits and the current source code. At this time, a new folder incubator-shardingsphere will be generated in your current directory, which is the entire project source code. You can see the current branch with the following command: git branch -vv The asterisk is the current branch. Adding remote branches Then we can use the command git remote add apache https://github.com/apache/incubator-shardingsphere Add the project under apache as one of our remote projects. Can be used later git fetch apache master: amaster Branch apache / master remotely and pull down locally to a new branch called amaster. Can also be used git checkout -b bmaster Pull a new branch called bmaster from the current branch. Then we can modify and debug on this branch. After the modification is completed, you can pass git add. git commit -a To submit changes. Finally we can pass git push Or follow the prompts and use set-upstream to push the new local branch to the remote branch with the same name in our own space. Submit PR At this point we can submit a PR on github. Move our branch to the apache / master branch. Compilation Instructions We generally use mvn clean package install To compile the project. Can also be used mvn clean package install -Prelease To package the project. Code style In order to be compatible with the previous version, the entire project compilation level has been Java 1.7, so the classes and features of Java 8 cannot be used at present, such as LocalDatetime or Stream API. The entire project needs to execute checkstyle at compile time, and the code specifications are stipulated in the checkstyle rules. E.g: -Cannot introduce unused imports -Javadoc must be added to public methods and classes, with the first sentence beginning with a capital and ending with an English period -Indentation uses 4 spaces, so we can turn on the option to show spaces in the IDE -Space is required after the comma -If statements need to have spaces after -Leave a blank line at the end of the file -Blank lines are not allowed within methods Some are subject to the same requirements as unit test code. Compile time At present, the entire project compilation takes about 22 minutes. There are a few tricks to reduce this time. Dependency Download Our project uses maven to download dependencies. If your machine is slow to access the maven central repository, you can consider using a domestic aliyun image. Specific methods can be searched online. If the dependency is downloaded for the first time on the day, the original download can be used in the future. You need to add -o to the mvn parameter to indicate offline compilation. For UI projects, you can first install the NodeJS environment locally, and then use cnpm instead of the original npm command. Can reduce 2/3 compilation time. Task branch It is recommended that for each project, a new branch is pulled from apache / master, and the name is the name of the project. Because the trunk has been changing, other partners are constantly maintaining and committing. If your task branch is not submitted on the day of the new pull branch, it is recommended to pull the apache / master and synchronize it to Branch of your own tasks, early detection of conflicts, and ensure that your branch can be merged with the trunk at any time. Refer to the following command: git checkout amaster git pull git checkout issue3402 git merge amaster After the task is completed (that is, PR and merged to apache / master), you can directly delete the branch: Git branch -D issue3402 Continuous Integration Currently, two continuous integrations are used in the project, one is apache jenkins and the other is travis-ci, which are triggered automatically when there is a PR submission in apache / incubator-shardingsphere. Because of the environment, if one of them reports an error, don't panic, and a success is usually enough, otherwise, check the detailed log for troubleshooting. Unit test DEMOExample 1 The development tool uses IDEA as an example to write unit tests for the following classes: org.apache.shardingsphere.orchestration.center.yaml.swapper.OrchestrationConfigurationYamlSwapper - Use the shortcut Ctrl + Shift + T in IDEA to add a unit test class for the current class. The default test class name is OrchestrationConfigurationYamlSwapperTest - Override methods written in the class, as there are 2 methods in the above class /** * Swap from InstanceConfiguration to YamlInstanceConfiguration. * * @param data data to be swapped * @return YAML instance configuration */ @Override public YamlOrchestrationConfiguration swap(final OrchestrationConfiguration data) { Map<String, YamlInstanceConfiguration> yamlInstanceConfigurationMap = new HashMap(); Map<String, InstanceConfiguration> instanceConfigurationMap = data.getInstanceConfigurationMap(); for (Entry<String, InstanceConfiguration> each : instanceConfigurationMap.entrySet()) { InstanceConfigurationYamlSwapper swapper = new InstanceConfigurationYamlSwapper(); yamlInstanceConfigurationMap.put(each.getKey(), swapper.swap(each.getValue())); } YamlOrchestrationConfiguration result = new YamlOrchestrationConfiguration(); result.setInstanceConfigurationMap(yamlInstanceConfigurationMap); return result; } /** * Swap from YamlInstanceConfiguration to InstanceConfiguration. * * @param yamlConfiguration YAML instance configuration * @return swapped object */ @Override public OrchestrationConfiguration swap(final YamlOrchestrationConfiguration yamlConfiguration) { Map<String, InstanceConfiguration> instanceConfigurationMap = new HashMap(); Map<String, YamlInstanceConfiguration> yamlInstanceConfigurationMap = yamlConfiguration.getInstanceConfigurationMap(); for (Entry<String, YamlInstanceConfiguration> each : yamlInstanceConfigurationMap.entrySet()) { InstanceConfigurationYamlSwapper swapper = new InstanceConfigurationYamlSwapper(); instanceConfigurationMap.put(each.getKey(), swapper.swap(each.getValue())); } OrchestrationConfiguration result = new OrchestrationConfiguration(instanceConfigurationMap); return result; } - The unit test method name starts with assert. Try to describe the content of this method as clearly as possible. The test code must follow the code specifications and ensure coverage. The above unit test methods are as follows： @Test public void assertSwapToYamlOrchestrationConfiguration() { OrchestrationConfiguration data = getOrchestrationConfiguration(); YamlOrchestrationConfiguration result = new OrchestrationConfigurationYamlSwapper().swap(data); for (String each : result.getInstanceConfigurationMap().keySet()) { assertNotNull(result.getInstanceConfigurationMap().get(each)); assertThat(result.getInstanceConfigurationMap().get(each).getOrchestrationType(), is(data.getInstanceConfigurationMap().get(each).getOrchestrationType())); assertThat(result.getInstanceConfigurationMap().get(each).getInstanceType(), is(data.getInstanceConfigurationMap().get(each).getType())); assertThat(result.getInstanceConfigurationMap().get(each).getNamespace(), is(data.getInstanceConfigurationMap().get(each).getNamespace())); assertThat(result.getInstanceConfigurationMap().get(each).getServerLists(), is(data.getInstanceConfigurationMap().get(each).getServerLists())); assertThat(result.getInstanceConfigurationMap().get(each).getProps(), is(data.getInstanceConfigurationMap().get(each).getProperties())); } } @Test public void assertSwapToOrchestrationConfiguration() { YamlOrchestrationConfiguration data = getYamlOrchestrationConfiguration(); OrchestrationConfiguration result = new OrchestrationConfigurationYamlSwapper().swap(data); for (String each : result.getInstanceConfigurationMap().keySet()) { assertNotNull(result.getInstanceConfigurationMap().get(each)); assertThat(result.getInstanceConfigurationMap().get(each).getOrchestrationType(), is(data.getInstanceConfigurationMap().get(each).getOrchestrationType())); assertThat(result.getInstanceConfigurationMap().get(each).getType(), is(data.getInstanceConfigurationMap().get(each).getInstanceType())); assertThat(result.getInstanceConfigurationMap().get(each).getNamespace(), is(data.getInstanceConfigurationMap().get(each).getNamespace())); assertThat(result.getInstanceConfigurationMap().get(each).getServerLists(), is(data.getInstanceConfigurationMap().get(each).getServerLists())); assertThat(result.getInstanceConfigurationMap().get(each).getProperties(), is(data.getInstanceConfigurationMap().get(each).getProps())); } } - For detailed development specifications, please refer to ShardingShphere Code of Conduct <https://shardingsphere.apache.org/community/cn/contribute/code-conduct/> Other Everyone is welcome to contribute code and documentation. If you have any questions during the period, you can always communicate on the issue board or group. Finally, we wish you all a pleasant trip to ShardingSphere. ：） -- Haoran Meng [email protected]
