Skip to content

Latest commit

 

History

History
174 lines (111 loc) · 6.99 KB

CONTRIBUTING.md

File metadata and controls

174 lines (111 loc) · 6.99 KB
Raw

For Contributor/Maintainers

Following contents help you to build your local development environment.

1. Download and install requirements.

  1. install Docker.
  2. set up your Java development environment.
  3. set up your Maven environment.

2. Set up your local development environment

  1. set your git config. (Setting your email as github private email address is one good practise.):
git config user.name $YOUR_GITHUB_NAME
git config user.email $YOUR_GITHUB_EMAIL
# to double check config
git config --local -l

# sign your code with GPG. GPG sign is optional but strongly recommended. 
git config commit.gpgsign true
  1. config your hosts in /etc/hosts。
127.0.0.1 kafka hbase proemtheus mysql zookeeper

That's all. Then follow the guidelines in README to run ETrace project.

Feel free to fork the project and push your request!

3. Set up GPG

GPG sign validate you codes and contribute. It's not mandatory but strongly recommended.

Signing commits doc on github explained how to sign the commits.

GPG Suite is a useful to maintain GPG key on MacOS.

Take this article for reference:

  1. install gnupg: brew install gpg .
  2. generate a key pair: gpg --gen-key. In the interactive, it require you a passphrase. Write it down, you'll sign your files by inputting this passphrase.(also can be set in maven setting.xml to pass the input)
  3. distribute your key to public. some available key servers are 'keys.gnupg.net', 'pool.sks-keyservers.net'.
gpg --keyserver hkp://keys.gnupg.net --send-keys YOUR_KEY_ID
gpg --keyserver hkp://pool.sks-keyservers.net --send-keys YOUR_KEY_ID

Follow the git commit message rule with Conventional Commits

What is Conventional Commits

Go to read its explanation, which contributes to the changes among codes.

Any tools to help?

Sure. IDE families of JetBrains provides a excellent plugin Git Commit Template.

Continues Integration

This part explain how ETrace project run [Continues Integration]. Default, test is ignored to simplify coding progress, but this github workflow will test every commit.

Unit Test

Run integration test: mvn verify -P unit-test.

Integration test

Current to run integration test: mvn verify -P integration-test.

Another way to run integration test: Maven Failsafe Plugin (not involved yet)

Deploy component to Central Maven Repository

automatically upload to Central Maven Repository

  1. Upgrade Release Version
mvn --batch-mode release:update-versions -DdevelopmentVersion=0.0.1-SNAPSHOT -DautoVersionSubmodules=true

  1. Then commit code and pull the request.

  2. On ETrace github page, create one release. Then corresponding github workflow will do the rest -- upload to Central Maven Repository automatically.

manual upload to Central Maven Repository

Sometime, you may want to deploy from your local machine (if you're the maintainer of this project).

  1. Prepare your environment: register an OSSRH account and configure to maven setting

The first, register a JIRA account. Then inform the maintainer of this project with your username. Then a new issue about allowing you to push the repository will be initiated and wait for the official approval.

When that issue resolved, add following settings to your maven 'setting.xml':

<server>
    <id>ossrh</id>
    <username>YOUR_JIRA_USERNAME</username>
    <password>YOUR_JIRA_PASSWORD</password>
</server>
  1. Upgrade Release Version
mvn --batch-mode release:update-versions -DdevelopmentVersion=0.0.1-SNAPSHOT -DautoVersionSubmodules=true

  1. Then commit code and pull the request.

  2. This project have included the maven-release-plugin to reduce the repetitive and manual work。

    1. run mvn release:prepare -DautoVersionSubmodules=true
    2. run mvn release:perform -Possrh

run mvn release:rollback if something goes wrong in the progress. And mvn release:clean to remove all generated files by release:prepare.

  1. Simply run mvn clean deploy -Possrh. it should work!

Related background information about Dev

How to update licence header to file

run mvn license:update-file-header command.

Spring security

  1. spring security manual
  2. Spring Security Architecture
  3. Spring Security Authentication Provider

Spring Data - ignore the parameter if it has a null value

Based on the answer on StackOverflow, this project adopt Example to handle nullable parameter in db query.

Go to io/etrace/api/service/DashboardService.java:52 for reference.

Also, keep watching Jira issue Improve handling of null query method parameter values and hope official team could support this via annotation.

Configuration and Pipeline Schema

1. utilize "Spring Configuration Metadata" to write correct application.yml

Approach 1: Define @ConfigurationProperties to related ETrace configuration. Your IDE will detect them automatically.

Approach 2: Write your own META-INF/spring-configuration-metadata.json to define the properties.

Reference: Configuration Metadata

2. utilize JSON schema to validate pipeline yaml configuration.

How it works? Boost your YAML with autocompletion and validation

So, you need to add schema/pipeline-schema.json to Preferences | Languages & Frameworks | Schemas and DTDs | JSON Schema Mappings, and apply to all file pattern of */pipeline/*.yml

How to update pipeline-schema.json? Learn Json Schema

Understanding JSON Schema