diff --git a/README.md b/README.md index caccdc73..616276c9 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,38 @@ # hsadminNg Development + + + +**Table of Contents** _generated with [DocToc](https://github.com/thlorenz/doctoc)_ + +- [Setting up the Development Environment](#setting-up-the-development-environment) +- [Frequent Tasks](#frequent-tasks) + - [Building the Application with Test Execution](#building-the-application-with-test-execution) + - [Starting the Application](#starting-the-application) + - [Running JUnit tests with branch coverage](#running-junit-tests-with-branch-coverage) +- [HOWTO Commits](#howto-commits) + - [Creating HOWTO Commits](#creating-howto-commits) +- [Special Build Tasks](#special-build-tasks) + - [Spotless Formatting](#spotless-formatting) + - [Mutation Testing PiTest](#mutation-testing-pitest) + - [Git Workflow for JHipster Generator](#git-workflow-for-jhipster-generator) + - [Generating the Table of Contents for Markdown](#generating-the-table-of-contents-for-markdown) + + + ## Setting up the Development Environment You'll often need to execute `./gradlew`, therefore we suggest to define this alias: alias gw='./gradlew' +TODO: Instructions for setting up the dev environment from scratch. + ## Frequent Tasks ### Building the Application with Test Execution -gw build + gw build ### Starting the Application @@ -31,45 +53,82 @@ 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. -## Git Workflow for JHipster Generator +## HOWTO Commits -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 entities) before changes to the JDL file can be imported. +There are git tags on some commits which show how to add certain features. -| WARNING: This is just a guideline. You should understand what you are doing! | -| ---------------------------------------------------------------------------- | +Find all of such tags with: + git tag | grep HOWTO - git checkout jhipster-generated - git pull - git tag REAL-HEAD - git reset --hard jdl-base - git clean -f -d - git cherry-pick -n spotless - git reset --soft REAL-HEAD - git checkout REAL-HEAD src/main/jdl/customer.jdl # AND OTHERS! - git tag -d REAL-HEAD +### Creating HOWTO Commits - # MANUAL STEP: Apply changes to the jdl file! +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. - # (Re-) Importing - jhipster import-jdl src/main/jdl/customer.jdl - jhipster import-jdl src/main/jdl/accessrights.jdl - # AND OTHERS, if applicable! +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 mutation testing.) + +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 --force origin HOWTO-... + +## 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. + +### Spotless Formatting + +To make sure that no IDE auto-formatter destroys the git history of any file and +especially to avoid merge conflicts from JHipster generated files after these had been changed, +we are using a standard formatter enforced by _spotless_, which is based on the standard Eclipse formatter. + +The rules can be checked and applied with these commands: + + gw spotlessCheck gw spotlessApply - git add . - git commit -m"..." - # MANUAL STEP: - # - if you've renamed any identifiers, use refactoring to rename in master as well BEFORE MERGING! +The spotlessCheck task is included as an early step in our Jenkins build pipeline. +Therefore wrong formatting is automatically detected. - # Merge changeset into master branch - git checkout master - git merge jhipster-generated +Our configuration can be found under the directory `cfg/spotless`. +Currently we only have specific rules for _\*.java_-files and their import-order. -### Amending the spotless commit +#### Our Changes to the Standard Eclipse Formatter + +We amended the Standard Eclipse Formatter in these respects: + +- Lines of code are never joined, thus the developer has control about linebreaks, + which is important for readability in some implementations like toString(). +- Lines in comments are never joined either, because that often destroys readable stucture. +- Parts of files can be excluded from getting formatted, by using `@formatter:off` and `@formatter:on` in a comment. + See for example in class `SecurityConfiguration`. + +#### Pre-Commit Hook + +If you like, you could add this code to the _pre-commit or \_pre_push_ hook\_ in your `.git/hooks` directory: + + if ! ./gradlew spotlessCheck; then + exit 1 + fi + +#### The Tagged Spotless Commit + +The commit which introduces the spotless configuration is tagged. +Through this tag it can easily be cherry-picked in the JHipster workflow. If you need to amend the commit tagged 'spotless', e.g. to change the spotless configuration, it can be done with these steps: @@ -87,43 +146,6 @@ it can be done with these steps: git reset --hard REAL-HEAD git tag -d REAL-HEAD -## HOWTO do This and That - -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 - -## 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 @@ -168,3 +190,97 @@ If you want to spend more CPU threads on your local system, you can change that gw pitest -Doverride.pitest.threads=7 I suggest to leave one CPU thread for other tasks or your might lag extremely. + +### Git Workflow for JHipster Generator + +The following workflow steps make sure that + +- JHipster re-imports work properly, +- the git history of changes to the JDL-files, the generated code and the master is comprehensible, +- and merging newly generated code to the master branch is smooth. + +It uses a git branch `jhipster-generated` to track the history of the JDL model file and the generated source code. +Applying commits which contain non-generated changes to that branch breaks the normal git history for generated files. +Therefore, this documentation is also not available in that branch. +Thus: + +**MANUAL STEP before starting:** Copy this workflow documentation, because this file will be gone once you switched the branch. + +| WARNING: The following steps are just a guideline. You should understand what you are doing! | +| -------------------------------------------------------------------------------------------- | + + +#### 1. Preparing the `jhipster-generated` git Branch + +This step assumes that the latest `*.jdl` files are on the `HEAD` of the `jhipster-generated` git branch. +On a re-import of a JDL-file, JHipster does not remove any generated classes which belong to entities deleted from the JDL-file. +Therefore, the project has to be reset to a clean state before changes to the JDL file can be re-imported. +We have not yet finally tested a simplified workflow for just adding new entities or properties. + +A git tag `jdl-base` is assumed to sit on the base commit after the application was generated, but before any entities were imported. + + git checkout jhipster-generated + git pull + git tag REAL-HEAD + git reset --hard jdl-base + git clean -f -d + git cherry-pick -n spotless + git reset --soft REAL-HEAD + git checkout REAL-HEAD src/main/jdl/customer.jdl # AND OTHERS! + git tag -d REAL-HEAD + +#### 2. Amending and Re-Importing the JDL + +**MANUAL STEP:** First apply all necessary changes to the JDL files. +Then re-import like this: + + # (Re-) Importing + jhipster import-jdl src/main/jdl/customer.jdl + jhipster import-jdl src/main/jdl/accessrights.jdl + jhipster import-jdl src/main/jdl/... # once there are more + +For smoothly being able to merge, we need the same formatting in the generated code as on the master: + + gw spotlessApply + +#### 3. Committing our Changes + + git add . + git commit -m"..." + +#### 4. Merging our Changes to the `master` Branch + + git checkout master + git pull + +**MANUAL STEP:** If you've renamed any identifiers, use the refactoring feature of your IDE to rename in master as well. +To avoid oodles of merge-conflicts, you need to do that **BEFORE MERGING!** +Commit any of such changes, if any. + +Now we can finally merge our changes to master. + + git merge jhipster-generated + +It's a good idea doing this step in an IDE because it makes conflict resolving much easier. +Typical merge conflicts stem from: + +- Random numbers in test data of `*IntTest.java` files. +- Timestamps in Liquibase-xml-Files. + +Now, I suggest to run all tests locally: + + gw clean test + +Once everything works again, we can push our new version: + + git push + +### Generating the Table of Contents for Markdown + +This README file contains a table of contents generated by _doctoc_. +It's quite simple to use: + +npm install -g doctoc +doctoc --maxlevel 3 README.md + +Further information can be found [https://github.com/thlorenz/doctoc/blob/master/README.md](on the _doctoc_ github page).