application overview

Signed-off-by: Jody Garnett <[email protected]>

CONTRIBUTING.md

@@ -5,29 +5,30 @@ Thank you for contributing to GeoNetwork:
 * 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.
 * 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.
 
-Pull requests: 
+# Pull requests
+
+* Pull request is required, even if you have commit access, so the tests are run and other developer can check your code.
 
-* Pull request is required, even if you have commit access, so the tests are run and other developer can check your code
 * Pull requests must be applied to `master`, before bing backported.
 
 * 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.
 
 * 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.
 
-* WIP: Use pull request draft (or even the text "WIP" to identify work in progress
+* Draft: Use pull request *Draft** (or even the text "WIP") to identify work in progress.
 
 * Rebase: No merge commits with current branch: use rebase!
 
-* API Change: Please identify any API change or behavior changes in commit messages
+* API Change: Please identify any API change or behavior changes in commit messages.
 
 * Review: Review is required by another person, or more than one! Don't be shy asking for help or reviewing.
 
-* Testing: All new features or enhancements require automatic tests
+* Testing: All new features or enhancements require automatic tests (see [testing](software_development/TESTING.md))
 
 * User documentation: All new features or enhancements require documentation (see [doc](https://github.com/geonetwork/doc))
 
 * Build documentation: All build and development instructions managed in repository `README.md` files.
 
-* New libraries: Do not commit jars, use maven `pom.xml` to declare dependencies where needed, and `src/pom.xml` dependency management for version numbers. Document what the library does in GeoNetwork, how it interacts or extends GeoNetwork, with references to official library tutorials or documentation.
+* 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.
 
 For more information see [How to contribute](https://github.com/geonetwork/core-geonetwork/wiki/How-to-contribute) (wiki).

README.md

@@ -1,3 +1,5 @@
+# GeoNetwork Open-soucce
+
 # Build Health
 
 [![Build Status](https://travis-ci.org/geonetwork/core-geonetwork.svg?branch=master)](https://travis-ci.org/geonetwork/core-geonetwork)
@@ -15,45 +17,13 @@
 
 # Documentation
 
-User documentation is in the docs submodule in the current repository and is compiled into html pages during a release for publishing on
-a website.
-
-Developer documentation is also in the docs submodule but is being migrated out of that project into the Readme files in each module
-in the project.  General documentation for the project as a whole is in this Readme and module specific documentation can be found in
-each module (assuming there is module specific documentation required).
-
-# Software Development
-
-Instructions for setting up a development environment/building Geonetwork/compiling user documentation/making a release see:
-[Software Development Documentation](/software_development/)
-
-# Testing
-
-With regards to testing Geonetwork is a standard Java project and primarily depends on JUnit for testing.  However there is a very important
-issue to consider when writing JUnit tests in Geonetwork and that is the separation between unit tests and integration tests
-
-* *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
-    the execution time of the unit tests very short.  Integration tests do not require super classes and any assistance methods can be static
-    imports, for example statically importing org.junit.Assert or org.junit.Assume or org.fao.geonet.Assert.
-* *Integration Tests* - Integration Test typically start much or all of Geonetwork as part of the test and will take longer to run than
-    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.
-    Starting Geonetwork in a way that isolates each integration test from each other integration test is non-trivial.  Because of this
-    there are `abstract` super classes to assist with this.  Many modules have module specific Abstract classes.  For example at the time
-    that this is being written `domain`, `core`, `harvesters` and `services` modules all have module specific super classes that need to
-    be used.  (`harvesting` has 2 superclasses depending on what is to be tested.)
-    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
-    you want to test.  The following list provides a few tips:
-    * *IMPORTANT*: All Integrations tests *must* end in IntegrationTest.  The build system assumes all tests ending in IntegrationTest is
-        an integration test and runs them in a build phase after unit tests.  All other tests are assumed to be unit tests.
-    * Prefer unit tests over Integration Tests because they are faster.
-    * Search the current module for IntegrationTest to find tests to model your integration test against
-    * This you might want integration tests for are:
-        * Services: If the service already exists and you quick need to write a test to debug/fix its behaviour.
-                    If you are writing a new service it is better to use Mockito to mock the dependencies of the service so the test is
-                    a unit test.
-        * Harvesters
-        * A behaviour that crosses much of the full system
-
-*org.fao.geonet.utils.GeonetHttpRequestFactory*: When making Http requests you should use org.fao.geonet.utils.GeonetHttpRequestFactory instead
-    of directly using HttpClient.  This is because there are mock instances of org.fao.geonet.utils.GeonetHttpRequestFactory that can
-    be used to mock responses when performing tests.
+User documentation is managed in the [geonetwork/doc](https://github.com/geonetwork/doc) repository covering all releases of GeoNetwork.
+
+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.
+
+Developer documentation located in README.md files in the code-base:
+
+* General documentation for the project as a whole is in this README.md
+* [Software Development Documentation](/software_development/) provides instructions for setting up a development environment, building Geonetwork, compiling user documentation, and making a releases
+* Module specific documentation can be found in each module (assuming there is module specific documentation required)
+

software_development/EclipseIDE.md

@@ -0,0 +1,148 @@
+# Eclipse setup
+
+The easiest way to develop GeoNetwork within Eclipse is with [m2e plugin](http://eclipse.org/m2e/),
+which comes by default on many Eclipse installations.
+
+## Import source code
+
+In order to import the source code, follow instructions below :
+
+* Press **File**> **Import** Menu item
+* In new dialog Select **Maven**> **Existing Maven Projects**
+* Press Next
+
+![Import existing projects into Eclipse](../eclipse-import-existing-projects.png)
+
+* In **Select root directory** field enter where your code is:
+ * example: C:\dev\geonetwork\trunk
+* Select All projects and Press **Finish** button. If another window appears, just continue without changing any option.
+
+It will take some minutes while the m2e plugin downloads all the Maven dependencies.
+
+## Debugging inside Eclipse
+
+* JRebel Plugin :
+
+Using the [JRebel plugin](http://zeroturnaround.com/software/jrebel/) is very useful for debugging in Eclipse.
+
+An example of the configuration file for JRebel may be the following:
+
+```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.zeroturnaround.com" xsi:schemaLocation="http://www.zeroturnaround.com http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
+
+      <classpath>
+    <dir name="------/web/target/classes"/>
+  </classpath>
+
+  <web>
+    <link target="/">
+      <dir name="--------/web/src/main/webapp">
+      </dir>
+    </link>
+         <link target="/">
+             <dir name="-------/web/target/webapp">
+             </dir>
+         </link>
+         <link target="/">
+             <dir name="--------/web/target/geonetwork">
+             </dir>
+         </link>
+  </web>
+
+ </application>
+```
+
+* Tomcat Server :
+
+Create a new Tomcat Server on Eclipse and add the geonetwork-main project as a web project.
+
+* Remote Debugging :
+
+ * [How do I configure Tomcat to support remote debugging?](http://wiki.apache.org/tomcat/FAQ/Developing#Q1)
+ * [How do I remotely debug Tomcat using Eclipse?](http://wiki.apache.org/tomcat/FAQ/Developing#Q2)
+
+## Code Quality Tools in Eclipse
+
+In order to see the same code quality warnings in Eclipse as Maven will detect, Find Bugs and Checkstyle need to be installed in your Eclipse install and configured as follows::
+
+* Start Eclipse
+* Go to **Help > Eclipse Marketplace**
+ * Install **findbugs**
+  * Don't Restart
+ * Install **checkstyle**
+  * Now Restart
+* Open preferences **Window > Preferences**
+ *  Select *Java > Code Style > Code Templates*
+  *  Select both Comments and Code elements
+  *  Click **Import** and import **code_quality/codetemplates.xml**
+ *  Select **Java > Code Style > Formatter**
+  *  Click **Import** and import **code_quality/formatter.xml**
+ *  Select **Java > Code Style > Clean Up**
+  *  Click **Import** and import **code_quality/cleanup.xml**
+ *  Select **Checkstyle**
+  * Click **New**
+  * Select **External Configuration**
+  * Enter any name (IE GeoNetwork)
+  * For **location** choose **code_quality/checkstyle_checks.xml**
+  * Press *OK*
+  * Select New configuration
+  * Press *Set as Default*
+ * Select **Java > FindBugs**
+  * Set **analysis effort** to **Maximum**
+  * Set **Minimum rank to report** to **2**
+  * Set **Minimum confidence to report** to **Medium**
+  * Check(enable) all bug categories
+  * Set all **Mark bugs with ... rank as** to **Warning**
+  * Change to _Filter files_ tab
+   * Add **code_quality/findbugs-excludes.xml** file to the **Exclude filter files**
+ * Close Preferences
+ * Right click on project in **Projects View** select **Checkstyle > Activate Checkstyle**
+ * Rebuild full project ( **Project > Clean...** )
+  * Checkstyle violations will show up as warnings
+ * Right click on project in **Projects View** select **Find Bugs > Find Bugs**
+   * FindBugs violations will show up as warnings
+
+## Code Quality Tools and Maven
+
+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. 
+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.)
+
+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.
+For example:
+
+```bash
+mvn install -DskipTests
+```
+
+Or if you want to run the tests but skip static analysis:
+
+```bash
+mvn install -P-run-static-analysis
+```
+
+That disables the profile that executes the static analysis tasks.
+
+### FindBugs
+
+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.
+
+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.
+In GeoNetwork the excludes filter file can be found at **<root>/code_quality/findbugs-excludes.xml**.
+
+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.
+
+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.
+
+## FindBugs Annotations (JSR 305)
+
+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
+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).
+
+Some resources for these annotations are:
+
+* http://vard-lokkur.blogspot.ch/2012/03/findbugs-and-jsr-305.html
+* http://www.infoq.com/news/2008/06/jsr-305-update
+* http://www.klocwork.com/blog/static-analysis/jsr-305-a-silver-bullet-or-not-a-bullet-at-all/
+* http://minds.coremedia.com/2012/10/31/jsr-305-nonnull-and-guava-preconditions/
+* 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)