2019-04-29 14:25:45 +02:00
|
|
|
# hsadminNg Development
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-29 14:25:45 +02:00
|
|
|
## Setting up the Development Environment
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-02 10:23:40 +02:00
|
|
|
You'll often need to execute `./gradlew`, therefore we suggest to define this alias:
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-02 10:23:40 +02:00
|
|
|
alias gw='./gradlew'
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-29 14:46:03 +02:00
|
|
|
## Frequent Tasks
|
|
|
|
|
|
|
|
### Building the Application with Test Execution
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-02 10:23:40 +02:00
|
|
|
gw build
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-29 14:46:03 +02:00
|
|
|
### Starting the Application
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-02 10:23:40 +02:00
|
|
|
Either simply:
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-02 10:23:40 +02:00
|
|
|
gw bootRun
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-02 10:23:40 +02:00
|
|
|
or with a specific port:
|
2019-04-01 13:14:56 +02:00
|
|
|
|
2019-04-02 10:23:40 +02:00
|
|
|
SERVER_PORT=8081 ./gradlew bootRun
|
2019-04-20 10:47:01 +02:00
|
|
|
|
2019-04-29 14:46:03 +02:00
|
|
|
### Running JUnit tests with branch coverage
|
2019-04-20 10:47:01 +02:00
|
|
|
|
2019-04-29 14:46:03 +02:00
|
|
|
#### for IntelliJ IDEA
|
2019-04-20 10:47:01 +02:00
|
|
|
|
|
|
|
see: https://confluence.jetbrains.com/display/IDEADEV/IDEA+Coverage+Runner
|
|
|
|
|
|
|
|
Either apply it to specific test configurations or,
|
|
|
|
better, delete the previous test configurations and amend the JUnit template.
|
2019-04-26 11:55:42 +02:00
|
|
|
|
2019-04-29 14:46:03 +02:00
|
|
|
## Git Workflow for JHipster Generator
|
2019-04-26 11:55:42 +02:00
|
|
|
|
|
|
|
The jhipster-generated git branch tracks the history of the JDL model file
|
|
|
|
and the generated source code. The project has to be resetted to a clean state
|
|
|
|
(without any generated entitites) before changes to the JDL file can be imported.
|
|
|
|
|
|
|
|
# Prepare/Cleanup Workspace
|
|
|
|
|
|
|
|
git checkout jhipster-generated
|
|
|
|
git reset --hard jdl-base
|
|
|
|
git clean -f -d
|
|
|
|
git checkout HEAD@{1} src/main/jdl/customer.jdl
|
|
|
|
git reset HEAD .
|
|
|
|
|
|
|
|
# Apply changes to the jdl file
|
|
|
|
|
|
|
|
# Invoke JHipster generator
|
|
|
|
|
|
|
|
jhipster import-jdl src/main/jdl/customer.jdl --force
|
|
|
|
|
|
|
|
# Let Git determine change set between most recent commit and the re-generated source
|
|
|
|
|
|
|
|
git reset --soft HEAD@{1}
|
|
|
|
git reset HEAD .
|
|
|
|
git add .
|
|
|
|
|
|
|
|
# Commit changeset
|
|
|
|
|
|
|
|
git commit -m '...'
|
|
|
|
|
|
|
|
# Merge changeset into master branch
|
|
|
|
|
|
|
|
git checkout master
|
|
|
|
git merge jhipster-generated
|
2019-04-29 14:25:45 +02:00
|
|
|
|
2019-04-29 14:46:03 +02:00
|
|
|
## HOWTO do This and That
|
2019-04-29 14:25:45 +02:00
|
|
|
|
|
|
|
There are git tags on some commits which show how to add certian features.
|
|
|
|
|
|
|
|
Find all of such tags with:
|
|
|
|
|
|
|
|
git tag | grep HOWTO
|
|
|
|
|
|
|
|
### creating HOWTO commits
|
|
|
|
|
|
|
|
If you want to add such a commit, make sure that it contains no clutter
|
|
|
|
(no changes which are not necessary for whatever the commit is about to explain),
|
|
|
|
and is complete with all unit tests, code coverage, pitest and other checks.
|
|
|
|
Otherwise the next developer would run into the same problems again.
|
|
|
|
|
|
|
|
One way to keep the commit clean, is to develop it on a local branch.
|
|
|
|
If any other changes (e.g. bugfixes, API extensions etc.) are necessary,
|
|
|
|
apply these only to the master or cherry-pick just these to the master,
|
|
|
|
then rebase your local branch. Do not forget to run all checks locally:
|
|
|
|
|
|
|
|
gw clean check pitest # might need over an hour
|
|
|
|
|
|
|
|
(Check the pitest section for speeding up pitest.)
|
|
|
|
|
|
|
|
To create and push a new tag use:
|
|
|
|
|
|
|
|
git tag HOWTO-... master
|
|
|
|
git push origin HOWTO-...
|
|
|
|
|
|
|
|
After you've moved an existing the tag to another commit, you can use:
|
|
|
|
|
|
|
|
git push origin HOWTO-... --force
|
2019-04-29 15:00:45 +02:00
|
|
|
|
|
|
|
## Special Build Tasks
|
|
|
|
|
|
|
|
Besides common build tasks like `build`, `test` or `bootRun` this projects has some not so common tasks which are explained in this section.
|
|
|
|
|
|
|
|
### Mutation Testing PiTest
|
|
|
|
|
|
|
|
./gradlew pitest
|
|
|
|
|
|
|
|
Runs (almost) all JUnit tests under mutation testing.
|
|
|
|
Mutation testing is a means to determine the quality of the tests.
|
|
|
|
|
2019-04-30 06:56:33 +02:00
|
|
|
On Jenkins, the results can be found in the build artifacts under:
|
|
|
|
|
|
|
|
- https://ci.hostsharing.net/job/hsadmin-ng-pitest/XX/artifact/build/reports/pitest/index.html
|
|
|
|
|
|
|
|
Where XX is the build number. Or for the latest build under:
|
|
|
|
|
|
|
|
- https://ci.hostsharing.net/job/hsadmin-ng-pitest/lastCompletedBuild/artifact/build/reports/pitest/index.html
|
|
|
|
|
2019-04-29 15:00:45 +02:00
|
|
|
#### Some Background Information on Mutation Testing
|
|
|
|
|
|
|
|
PiTest does it with these steps:
|
|
|
|
|
|
|
|
- initially PiTest checks which production code is executed by which tests
|
|
|
|
- if the tests don't pass, it stops
|
|
|
|
- otherwise the production code is 'mutated' and PiTest checks whether this makes a test fail ('mutant killed')
|
|
|
|
- Finally it checks thresholds for coverage and mutant killing.
|
|
|
|
|
|
|
|
More information about can be found here:
|
|
|
|
|
|
|
|
- PiTest: http://pitest.org/
|
|
|
|
- gradle-plugin: https://gradle-pitest-plugin.solidsoft.info/
|
|
|
|
|
|
|
|
#### How to Configure PiTest
|
|
|
|
|
|
|
|
These thresholds can be configured in `build.gradle`,
|
|
|
|
but we should generally not lower these.
|
|
|
|
|
|
|
|
There is also a list of excluded files, all generated by JHipster or MapStruct, not containing any changes by us.
|
|
|
|
|
|
|
|
As you might figure, mutation testing is CPU-hungry.
|
|
|
|
To limit load in our Jenkins build server, it only uses 2 CPU threads, thus it needs over an hour.
|
|
|
|
|
|
|
|
If you want to spend more CPU threads on your local system, you can change that via command line:
|
|
|
|
|
|
|
|
./gradlew pitest -Doverride.pitest.threads=7
|
|
|
|
|
|
|
|
I suggest to leave one CPU thread for other tasks or your might lag extremely.
|