Skip to content

Commit 5ee19a2

Browse files
jodygarnettjodygarnett
authored
Update software instructions, standard license and contributing files (geonetwork#4697)
Signed-off-by: Jody Garnett <[email protected]>
1 parent 299850f commit 5ee19a2

19 files changed

+965
-569
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -82,3 +82,4 @@ chromedriver
8282
node_modules
8383
package-lock.json
8484
.project
85+
.DS_Store

‎CONTRIBUTING.md

+33-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,34 @@
1+
# Contributing
12

2-
Please have a look at our contributing guidelines at https://github.com/geonetwork/core-geonetwork/wiki/How-to-contribute
3+
Thank you for contributing to GeoNetwork:
4+
5+
* Free-software: GeoNetwork is free-software, using the [GNU GENERAL PUBLIC LICENSE](LICENSE.md). Contributions provided by you, or your employer, are required to be compatible with this free-software license.
6+
* Pull-request: GeoNetwork uses a pull-request workflow to review and accept changes. Pull-requests must be submitted against the *master* branch first, and may be back ported as required.
7+
8+
# Pull requests
9+
10+
* Pull request is required, even if you have commit access, so the tests are run and other developer can check your code.
11+
12+
* Pull requests must be applied to `master`, before being backported.
13+
14+
* Good housekeeping: Anytime you commit, try and clean the code around it to latest style guide. If you improve a function without comments: add comments. If you modify functionality that does not have tests: write a test. If you fix functionality without documentation: add documentation.
15+
16+
* History: Clean commit messages and history: avoid big commits with hundreds of files, break commits commits up into understandable chunks, longer verbose commit messages are encouraged. Beware of reformatting and needless whitespace changes.
17+
18+
* Draft: Use pull request *Draft** (or even the text "WIP") to identify work in progress.
19+
20+
* Rebase: No merge commits with current branch: use rebase!
21+
22+
* API Change: Please identify any API change or behavior changes in commit messages.
23+
24+
* Review: Review is required by another person, or more than one! Don't be shy asking for help or reviewing.
25+
26+
* Testing: All new features or enhancements require automatic tests (see [testing](software_development/TESTING.md))
27+
28+
* User documentation: All new features or enhancements require documentation (see [doc](https://github.com/geonetwork/doc))
29+
30+
* Build documentation: All build and development instructions managed in repository `README.md` files.
31+
32+
* New libraries: Do not commit jars, use maven `pom.xml` to declare dependencies where needed, and `src/pom.xml` dependency management to manage version numbers. Document what the library does in GeoNetwork, how it interacts or extends GeoNetwork, with references to official library tutorials or documentation.
33+
34+
For more information see [How to contribute](https://github.com/geonetwork/core-geonetwork/wiki/How-to-contribute) (wiki).

‎LICENSE

-339
This file was deleted.

‎LICENSE.md

+361
Large diffs are not rendered by default.

‎README.md

+12-42
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# GeoNetwork Open-soucce
2+
13
# Build Health
24

35
[![Build Status](https://travis-ci.org/geonetwork/core-geonetwork.svg?branch=master)](https://travis-ci.org/geonetwork/core-geonetwork)
@@ -15,45 +17,13 @@
1517

1618
# Documentation
1719

18-
User documentation is in the docs submodule in the current repository and is compiled into html pages during a release for publishing on
19-
a website.
20-
21-
Developer documentation is also in the docs submodule but is being migrated out of that project into the Readme files in each module
22-
in the project. General documentation for the project as a whole is in this Readme and module specific documentation can be found in
23-
each module (assuming there is module specific documentation required).
24-
25-
# Software Development
26-
27-
Instructions for setting up a development environment/building Geonetwork/compiling user documentation/making a release see:
28-
[Software Development Documentation](/software_development/)
29-
30-
# Testing
31-
32-
With regards to testing Geonetwork is a standard Java project and primarily depends on JUnit for testing. However there is a very important
33-
issue to consider when writing JUnit tests in Geonetwork and that is the separation between unit tests and integration tests
34-
35-
* *Unit Tests* - In Geonetwork unit tests should be very very quick to execute and not start up any subsystems of the application in order to keep
36-
the execution time of the unit tests very short. Integration tests do not require super classes and any assistance methods can be static
37-
imports, for example statically importing org.junit.Assert or org.junit.Assume or org.fao.geonet.Assert.
38-
* *Integration Tests* - Integration Test typically start much or all of Geonetwork as part of the test and will take longer to run than
39-
a unit test. However, even though the tests take longer they should still be implemented in such a way to be as efficient as possible.
40-
Starting Geonetwork in a way that isolates each integration test from each other integration test is non-trivial. Because of this
41-
there are `abstract` super classes to assist with this. Many modules have module specific Abstract classes. For example at the time
42-
that this is being written `domain`, `core`, `harvesters` and `services` modules all have module specific super classes that need to
43-
be used. (`harvesting` has 2 superclasses depending on what is to be tested.)
44-
The easiest way to learn how to implement an integration test is to search for other integration tests in the same module as the class
45-
you want to test. The following list provides a few tips:
46-
* *IMPORTANT*: All Integrations tests *must* end in IntegrationTest. The build system assumes all tests ending in IntegrationTest is
47-
an integration test and runs them in a build phase after unit tests. All other tests are assumed to be unit tests.
48-
* Prefer unit tests over Integration Tests because they are faster.
49-
* Search the current module for IntegrationTest to find tests to model your integration test against
50-
* This you might want integration tests for are:
51-
* Services: If the service already exists and you quick need to write a test to debug/fix its behaviour.
52-
If you are writing a new service it is better to use Mockito to mock the dependencies of the service so the test is
53-
a unit test.
54-
* Harvesters
55-
* A behaviour that crosses much of the full system
56-
57-
*org.fao.geonet.utils.GeonetHttpRequestFactory*: When making Http requests you should use org.fao.geonet.utils.GeonetHttpRequestFactory instead
58-
of directly using HttpClient. This is because there are mock instances of org.fao.geonet.utils.GeonetHttpRequestFactory that can
59-
be used to mock responses when performing tests.
20+
User documentation is managed in the [geonetwork/doc](https://github.com/geonetwork/doc) repository covering all releases of GeoNetwork.
21+
22+
The `docs` folder includes [geonetwork/doc](https://github.com/geonetwork/doc) as a git submodule. This documentation is compiled into html pages during a release for publishing on the [geonetwork-opensource.org](http://geonetwork-opensource.org) website.
23+
24+
Developer documentation located in README.md files in the code-base:
25+
26+
* General documentation for the project as a whole is in this README.md
27+
* [Software Development Documentation](/software_development/) provides instructions for setting up a development environment, building Geonetwork, compiling user documentation, and making a releases
28+
* Module specific documentation can be found in each module (assuming there is module specific documentation required)
29+

‎software_development/BUILDING.md

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Building
2+
3+
See [Installing from source code](https://geonetwork-opensource.org/manuals/trunk/en/maintainer-guide/installing/installing-from-source-code.html) (Maintainer Guide)
4+
5+
Build GeoNetwork
6+
----------------
7+
8+
Once you checked out the code from Github repository, go inside the GeoNetwork’s root folder and execute the maven build command:
9+
10+
```
11+
mvn clean install
12+
```
13+
14+
If the build is successful you'll get an output like:
15+
```
16+
[INFO]
17+
[INFO] ------------------------------------------------------------------------
18+
[INFO] Reactor Summary:
19+
[INFO] ------------------------------------------------------------------------
20+
[INFO] GeoNetwork opensource ................................. SUCCESS [1.345s]
21+
[INFO] Caching xslt module ................................... SUCCESS [1.126s]
22+
[INFO] Jeeves modules ........................................ SUCCESS [3.970s]
23+
[INFO] ArcSDE module (dummy-api) ............................. SUCCESS [0.566s]
24+
[INFO] GeoNetwork web client module .......................... SUCCESS [23.084s]
25+
[INFO] GeoNetwork user interface module ...................... SUCCESS [15.940s]
26+
[INFO] Oaipmh modules ........................................ SUCCESS [1.029s]
27+
[INFO] GeoNetwork domain ..................................... SUCCESS [0.808s]
28+
[INFO] GeoNetwork core ....................................... SUCCESS [6.426s]
29+
[INFO] GeoNetwork CSW server ................................. SUCCESS [2.050s]
30+
[INFO] GeoNetwork health monitor ............................. SUCCESS [1.014s]
31+
[INFO] GeoNetwork harvesters ................................. SUCCESS [2.583s]
32+
[INFO] GeoNetwork services ................................... SUCCESS [3.178s]
33+
[INFO] GeoNetwork Web module ................................. SUCCESS [2:31.387s]
34+
[INFO] ------------------------------------------------------------------------
35+
[INFO] ------------------------------------------------------------------------
36+
[INFO] BUILD SUCCESSFUL
37+
[INFO] ------------------------------------------------------------------------
38+
[INFO] Total time: 3 minutes 35 seconds
39+
[INFO] Finished at: Sun Oct 27 16:21:46 CET 2013
40+
```
41+
42+
Your local maven repository now contain the GeoNetwork artifacts created (``$HOME/.m2/repository/org/geonetwork-opensource``).
43+
44+
Compilation options
45+
-------------------
46+
47+
Many Maven build options are available, for instance, you might like to use following options :
48+
49+
* To skip tests:
50+
51+
```
52+
mvn install -DskipTests
53+
```
54+
55+
* Offline use:
56+
57+
```
58+
mvn install -o
59+
```
60+
61+
* Build really fast with 2 threads per cpu core
62+
63+
```
64+
mvn install -o -DskipTests -T 2C
65+
```
66+
67+
Please refer to the maven documentation for additional options, [Maven: The Complete Reference](http://www.sonatype.com/books/mvnref-book/reference/public-book.html)
68+
69+
Maven Profiles
70+
--------------
71+
72+
Maven profiles are used to enable additional build configuration.
73+
74+
Some components (eg. WFS feature indexing) of the application rely on an Elasticsearch instance. To enable those options, build the application with the ```es``` profile.
75+
76+
```
77+
mvn clean install -Pes
78+
```
79+
80+
Run embedded Jetty server
81+
-------------------------
82+
83+
Maven comes with built-in support for Jetty via a [plug-in](https://www.eclipse.org/jetty/documentation/current/jetty-maven-plugin.html)
84+
85+
To run GeoNetwork with the embedded Jetty server you have to change directory to the root of the **web** module,
86+
and then execute the following maven command:
87+
88+
```
89+
cd web
90+
mvn jetty:run -Penv-dev
91+
```
92+
93+
After a moment, GeoNetwork should be accessible at: http://localhost:8080/geonetwork
94+
95+
For changes related to the user interface in the `web-ui` module or the metadata schemas in the `schemas` module, can be deployed in jetty executing the following maven command in the **web** module:
96+
97+
```
98+
mvn process-resources
99+
```

‎software_development/ECLIPSE.md

+176
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Eclipse IDE
2+
3+
The [Eclipse Foundation](https://www.eclipse.org/) produces several distributions of the Eclipse IDE. The "Eclipse IDE for Java Developers" and "Eclipse IDE for Enterprise Java Developers" can be used for GeoNetwork development.
4+
5+
Eclipse provides maven integration using the built-in [M2Eclipse](http://eclipse.org/m2e/) plugin.
6+
7+
The Eclipse IDE is recommended for excellent refactoring support.
8+
9+
## Import source code
10+
11+
In order to import the source code, follow instructions below:
12+
13+
1. Press **File** > **Import** Menu item
14+
2. In new dialog Select **Maven** > **Existing Maven Projects**
15+
3. Press *Next*
16+
17+
![Import existing projects into Eclipse](../eclipse-import-existing-projects.png)
18+
19+
4. In **Select root directory** field enter the location of your source code:
20+
21+
* `C:\dev\geonetwork\trunk`
22+
23+
5. Select All projects and Press **Finish** button.
24+
25+
6. During the import process Eclipse will attempt to map each maven plugin to matching
26+
functionality provided by the Eclipse IDE.
27+
28+
If another window appears showing these associations, just continue without changing any option.
29+
30+
7. It will take some minutes while the m2e plugin downloads all the Maven dependencies.
31+
32+
## Building
33+
34+
The Eclispe IDE is configured to respect the `src` and `target` locations defined by the maven `pom.xml` file.
35+
36+
* Eclipse makes use of an incremental compiler, allowing classes to be changed during debugging sessions.
37+
38+
* If you build on the command line, be sure to run a clean build in Eclipse when switching back to the IDE.
39+
40+
## Running with Jetty
41+
42+
Use **Run As** > **Maven Build** to use `jetty:run` from inside Eclipse.
43+
44+
You can add some maven variables to be able to run in parallel a debug watch to debug your code.
45+
46+
## Debugging with JRebel Plugin
47+
48+
Using the [JRebel plugin](http://zeroturnaround.com/software/jrebel/) is very useful for debugging in Eclipse.
49+
50+
An example of the configuration file for JRebel may be the following:
51+
52+
```xml
53+
54+
<?xml version="1.0" encoding="UTF-8"?>
55+
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
56+
xmlns="http://www.zeroturnaround.com"
57+
xsi:schemaLocation="http://www.zeroturnaround.com http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
58+
<classpath>
59+
<dir name="------/web/target/classes"/>
60+
</classpath>
61+
62+
<web>
63+
<link target="/">
64+
<dir name="--------/web/src/main/webapp">
65+
</dir>
66+
</link>
67+
<link target="/">
68+
<dir name="-------/web/target/webapp">
69+
</dir>
70+
</link>
71+
<link target="/">
72+
<dir name="--------/web/target/geonetwork">
73+
</dir>
74+
</link>
75+
</web>
76+
77+
</application>
78+
```
79+
80+
## Debugging with Tomcat Server
81+
82+
The Eclipse for [Web Tools Project](https://www.eclipse.org/webtools/) includes a
83+
Tomcat Plugin for controlling a Tomcat Service.
84+
85+
#. Create a new Tomcat Server on Eclipse and add the geonetwork-main project as a web project.
86+
87+
## Remote Debugging
88+
89+
* [How do I configure Tomcat to support remote debugging?](http://wiki.apache.org/tomcat/FAQ/Developing#Q1)
90+
* [How do I remotely debug Tomcat using Eclipse?](http://wiki.apache.org/tomcat/FAQ/Developing#Q2)
91+
92+
## Code Quality Tools in Eclipse
93+
94+
In order to see the same code quality warnings in Eclipse as Maven will detect, Find Bugs and Checkstyle
95+
need to be installed in your Eclipse install and configured as follows::
96+
97+
* Start Eclipse
98+
* Go to **Help > Eclipse Marketplace**
99+
* Install **findbugs**
100+
* Don't Restart
101+
* Install **checkstyle**
102+
* Now Restart
103+
* Open preferences **Window > Preferences**
104+
* Select *Java > Code Style > Code Templates*
105+
* Select both Comments and Code elements
106+
* Click **Import** and import **code_quality/codetemplates.xml**
107+
* Select **Java > Code Style > Formatter**
108+
* Click **Import** and import **code_quality/formatter.xml**
109+
* Select **Java > Code Style > Clean Up**
110+
* Click **Import** and import **code_quality/cleanup.xml**
111+
* Select **Checkstyle**
112+
* Click **New**
113+
* Select **External Configuration**
114+
* Enter any name (IE GeoNetwork)
115+
* For **location** choose **code_quality/checkstyle_checks.xml**
116+
* Press *OK*
117+
* Select New configuration
118+
* Press *Set as Default*
119+
* Select **Java > FindBugs**
120+
* Set **analysis effort** to **Maximum**
121+
* Set **Minimum rank to report** to **2**
122+
* Set **Minimum confidence to report** to **Medium**
123+
* Check(enable) all bug categories
124+
* Set all **Mark bugs with ... rank as** to **Warning**
125+
* Change to _Filter files_ tab
126+
* Add **code_quality/findbugs-excludes.xml** file to the **Exclude filter files**
127+
* Close Preferences
128+
* Right click on project in **Projects View** select **Checkstyle > Activate Checkstyle**
129+
* Rebuild full project ( **Project > Clean...** )
130+
* Checkstyle violations will show up as warnings
131+
* Right click on project in **Projects View** select **Find Bugs > Find Bugs**
132+
* FindBugs violations will show up as warnings
133+
134+
## Code Quality Tools and Maven
135+
136+
During the build process FindBugs and Checkstyle are executed. If a violation is found then the build will fail. Usually the easiest way of resolving violations are to use Eclipse and run Checkstyle or FindBugs on the class or project with the failure.
137+
Usually a detailed report will be provided in Eclipse along with suggested fixes. If the violation is determined to be an intentional violation the **code_quality/findbugs-excludes.xml** or **code_quality/checkstyle_suppressions.xml** should be updated to suppress the reporting of the violation. (See FindBugs and Checkstyle sections for more details.)
138+
139+
Since the FindBugs and Checkstyle processes can be quite time consuming, adding -DskipTests to the maven commandline will skip those processes as well as tests.
140+
For example:
141+
142+
```bash
143+
mvn install -DskipTests
144+
```
145+
146+
Or if you want to run the tests but skip static analysis:
147+
148+
```bash
149+
mvn install -P-run-static-analysis
150+
```
151+
152+
That disables the profile that executes the static analysis tasks.
153+
154+
### FindBugs
155+
156+
FindBugs is a tool that statically analyzes Java class files and searches for potential bugs. It excels at finding issues like unclosed reasources, inconsistent locking of resources, refering null known null-values. It also checks for bad practices like using default platform charset instead of an explicit charset.
157+
158+
Because bad practices are checked for, sometimes FindBugs detects issues that are intentional. In order to account for these intentional violations FindBugs has exclude filter files which contain rules for violations that should be ignored.
159+
In GeoNetwork the excludes filter file can be found at **<root>/code_quality/findbugs-excludes.xml**.
160+
161+
For complete details of how to specify matches in the excludes file see http://findbugs.sourceforge.net/manual/filter.html and look at the existing examples in the file.
162+
163+
The Maven build will fail if any violations are detected so it is important to run FindBugs on each project and fix or exclude each violation that is reported.
164+
165+
## FindBugs Annotations (JSR 305)
166+
167+
In order to get the maximum benefit from the FindBugs (and Eclipse) analysis the javax.annotation annotations can be used to add metadata to methods, fields and parameters. The most commonly used annotations are @CheckForNull and @Nonnull. These
168+
can be used on a parameter or return value to indicate that the parameter or return value must not be null or may be null. The FindBugs process will enforce these conditions and statically check that null is only ever correctly returned (in the case of return values) or passed to a method (in the case of parameters).
169+
170+
Some resources for these annotations are:
171+
172+
* http://vard-lokkur.blogspot.ch/2012/03/findbugs-and-jsr-305.html
173+
* http://www.infoq.com/news/2008/06/jsr-305-update
174+
* http://www.klocwork.com/blog/static-analysis/jsr-305-a-silver-bullet-or-not-a-bullet-at-all/
175+
* http://minds.coremedia.com/2012/10/31/jsr-305-nonnull-and-guava-preconditions/
176+
* http://findbugs.sourceforge.net/manual/annotations.html (the package names are out of date and should be java.annotation instead of edu.umd.cs.findbugs.annotation but the descriptions are accurate)

0 commit comments

Comments
 (0)