README.MD 6.57 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# DDA

This application was generated using JHipster, you can find documentation and help at [https://jhipster.github.io](https://jhipster.github.io).

Before you can build this project, you must install and configure the following dependencies on your machine:

1. [Node.js][]: We use Node to run a development web server and build the project.
   Depending on your system, you can install Node either from source or as a pre-packaged bundle.

After installing Node, you should be able to run the following command to install development tools (like
[Bower][] and [BrowserSync][]). You will only need to run this command when dependencies change in package.json.

    npm install

We use [Grunt][] as our build system. Install the grunt command-line tool globally with:

17
    npm install -g grunt-cli bower
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

Run the following commands in two separate terminals to create a blissful development experience where your browser
auto-refreshes when files change on your hard drive.

    mvn
    grunt

Bower is used to manage CSS and JavaScript dependencies used in this application. You can upgrade dependencies by
specifying a newer version in `bower.json`. You can also run `bower update` and `bower install` to manage dependencies.
Add the `-h` flag on any command to see how you can use it. For example, `bower update -h`.

# Building for production

To optimize the DDA client for production, run:

    mvn -Pprod clean package

This will concatenate and minify CSS and JavaScript files. It will also modify `index.html` so it references
these new files.

To ensure everything worked, run:

    java -jar target/*.war --spring.profiles.active=prod

Then navigate to [http://localhost:8080](http://localhost:8080) in your browser.

# Testing

Unit tests are run by [Karma][] and written with [Jasmine][]. They're located in `src/test/javascript` and can be run with:

    grunt test

50
# Development
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
## Development methodology
#### Fixing bugs and building features on dedicated branches
It is a best practice to fix a bug and develop a new feature on a dedicated git branch, then, after finishing that task, merging the made changes back into the *master* branch.
* For the whole development group, this helps in maintaining a working DDA Wizard version in the *master* branch - it will never contain a half-baked version.
* For the individual developer(s) working on the branch, it helps to develop on their task with a known DDA Wizard git project state, and changes on the *master* made concurrently by others won't interfere with their work.
* The finalizing merge into master allows to see the *set of changes* made to the whole DDA Wizard git project that are required to show *what* had to be changed in order to fulfill the feature/bugfix.

Follow the following steps in order to work with branches:

```
cd ~/git/dda-wizard/

git checkout master

# get the current DDA Wizard repository state into your local repository
git pull

# create a new FEATURE or BUGFIX branch and give it a meaningful name
git checkout -b FEATURE-fancy-feature

# ... make modifications on this branch FEATURE-fancy-feature
# commit these changes,
# and in case a work-in-progress at the end of the day leaves your branch in an inconsistent, nonworking state,
# then add a 'WIP' work in progress prefix for references.
git add X Y Z
git commit -m "WIP foo"

# save those changes also on the upstream branch
git push
# maybe on first branch push, git will ask you to set the upstream branch... 
# ... in that case, just copy and paste the set-upstream command as provided by git

# make some more edits, adds and commits on the local branch...

# you now think you have finished all work on this branch, git push your branch a final time ...
# DDA Wizard's Jenkins will deploy your branch to dda-wizard.svko-dda-test.gesis.intra ...
# Have all feature/bugfix stakeholders (e.g. Agathe) play with the svko-dda-test instance and give you feedback

# Assuming now that you and all others are happy with what this branch provides, merge that branch into master ...
# First you checkout your local master branch
git checkout master

# fetch and merge latest origin/master commits into your local master branch:
git pull

# now local master branch is up-to-date

# now merge local FEATURE-fancy-feature into your local master:
git merge --no-ff FEATURE-fancy-feature
# in case of merge conflicts, resolve the conflicts (hint: `git mergetool`)
git commit # that's right, don't provide a commit message. Git will generate one for you.

# assuming "merge --no-ff ..." worked, push this commit to remote repository...

git push

# make a final quality assurance test on svko-dda-test, and make sure that both your new changes and all previously developed features and bugfixes work smoothly together...
```
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

## In-memory database
You can interact with the h2 in-memory database by visiting its web interface at [http://localhost:8080/h2-console](http://localhost:8080/h2-console). As *JDBC URL*, provide `jdbc:h2:mem:dda`. As *User Name*, provide DDA. Keep *Password* empty.

## Debugging
The `dev` profile activates Java debugging capability. You can connect a client debugger by pointing it to `localhost:5005`.

## Project source filesystem layout
    /       <--- development- and build- relevant files, including this README.MD, pom.xml, package.json, Gruntfile.js ... not part of the final build artifact
    |- src/
        |- main/
            |- java/      <--- dda-wizard Java source files
            |- resources/ <--- in the final build artifact, its content will land in /WEB-INF/classes/. This content won't be served out as files via HTTP.
            |- scss/      <--- Gruntfile.js configures the grunt-sass task to process SASS stylesheets in this directory
            |- webapp/    <--- in the final build artifact, its content will land in /. This content will be served out as files via HTTP!
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149


# Continuous Integration

To setup this project in Jenkins, use the following configuration:

* Project name: `DDA`
* Source Code Management
    * Git Repository: `git@github.com:xxxx/DDA.git`
    * Branches to build: `*/master`
    * Additional Behaviours: `Wipe out repository & force clone`
* Build Triggers
    * Poll SCM / Schedule: `H/5 * * * *`
* Build
    * Invoke Maven / Tasks: `-Pprod clean package`
* Post-build Actions
    * Publish JUnit test result report / Test Report XMLs: `build/test-results/*.xml`

[JHipster]: https://jhipster.github.io/
[Node.js]: https://nodejs.org/
[Bower]: http://bower.io/
[Grunt]: http://gruntjs.com/
[BrowserSync]: http://www.browsersync.io/
[Karma]: http://karma-runner.github.io/
[Jasmine]: http://jasmine.github.io/2.0/introduction.html
[Protractor]: https://angular.github.io/protractor/