Update software instructions, standard license and contributing files (…

…#4697) Signed-off-by: Jody Garnett <[email protected]>
geonetwork · Jun 16, 2020 · 8384317 · 8384317
1 parent ad36cda
commit 8384317
Show file tree

Hide file tree

Showing 19 changed files with 965 additions and 569 deletions.
diff --git a/.gitignore b/.gitignore
@@ -82,3 +82,4 @@ chromedriver
 node_modules
 package-lock.json
 .project
+.DS_Store
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,2 +1,34 @@
+# Contributing
 
-Please have a look at our contributing guidelines at https://github.com/geonetwork/core-geonetwork/wiki/How-to-contribute
+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 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 being 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. Beware of reformatting and needless whitespace changes.
+
+* 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.
+
+* 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 (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 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).
diff --git a/LICENSE b/LICENSE
diff --git a/LICENSE.md b/LICENSE.md
diff --git a/README.md b/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)
+
diff --git a/software_development/BUILDING.md b/software_development/BUILDING.md
@@ -0,0 +1,99 @@
+# Building
+
+See [Installing from source code](https://geonetwork-opensource.org/manuals/trunk/en/maintainer-guide/installing/installing-from-source-code.html) (Maintainer Guide)
+
+Build GeoNetwork
+----------------
+
+Once you checked out the code from Github repository, go inside the GeoNetwork’s root folder and execute the maven build command:
+
+```
+mvn clean install
+```
+
+If the build is successful you'll get an output like:
+```
+[INFO]
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Summary:
+[INFO] ------------------------------------------------------------------------
+[INFO] GeoNetwork opensource ................................. SUCCESS [1.345s]
+[INFO] Caching xslt module ................................... SUCCESS [1.126s]
+[INFO] Jeeves modules ........................................ SUCCESS [3.970s]
+[INFO] ArcSDE module (dummy-api) ............................. SUCCESS [0.566s]
+[INFO] GeoNetwork web client module .......................... SUCCESS [23.084s]
+[INFO] GeoNetwork user interface module ...................... SUCCESS [15.940s]
+[INFO] Oaipmh modules ........................................ SUCCESS [1.029s]
+[INFO] GeoNetwork domain ..................................... SUCCESS [0.808s]
+[INFO] GeoNetwork core ....................................... SUCCESS [6.426s]
+[INFO] GeoNetwork CSW server ................................. SUCCESS [2.050s]
+[INFO] GeoNetwork health monitor ............................. SUCCESS [1.014s]
+[INFO] GeoNetwork harvesters ................................. SUCCESS [2.583s]
+[INFO] GeoNetwork services ................................... SUCCESS [3.178s]
+[INFO] GeoNetwork Web module ................................. SUCCESS [2:31.387s]
+[INFO] ------------------------------------------------------------------------
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 3 minutes 35 seconds
+[INFO] Finished at: Sun Oct 27 16:21:46 CET 2013
+```
+
+Your local maven repository now contain the GeoNetwork artifacts created (``$HOME/.m2/repository/org/geonetwork-opensource``).
+
+Compilation options
+-------------------
+
+Many Maven build options are available, for instance, you might like to use following options :
+
+* To skip tests:
+
+  ```
+  mvn install -DskipTests
+  ```
+
+* Offline use:
+
+  ```
+  mvn install -o
+  ```
+
+* Build really fast with 2 threads per cpu core
+
+  ```
+  mvn install -o -DskipTests -T 2C
+  ```
+
+Please refer to the maven documentation for additional options, [Maven: The Complete Reference](http://www.sonatype.com/books/mvnref-book/reference/public-book.html)
+
+Maven Profiles
+--------------
+
+Maven profiles are used to enable additional build configuration.
+
+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.
+
+```
+mvn clean install -Pes
+```
+
+Run embedded Jetty server
+-------------------------
+
+Maven comes with built-in support for Jetty via a [plug-in](https://www.eclipse.org/jetty/documentation/current/jetty-maven-plugin.html)
+
+To run GeoNetwork with the embedded Jetty server you have to change directory to the root of the **web** module,
+and then execute the following maven command:
+
+```
+cd web
+mvn jetty:run -Penv-dev
+```
+
+After a moment, GeoNetwork should be accessible at: http://localhost:8080/geonetwork
+
+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:
+
+```
+mvn process-resources
+```
diff --git a/software_development/ECLIPSE.md b/software_development/ECLIPSE.md
@@ -0,0 +1,176 @@
+# Eclipse IDE
+
+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.
+
+Eclipse provides maven integration using the built-in [M2Eclipse](http://eclipse.org/m2e/) plugin.
+
+The Eclipse IDE is recommended for excellent refactoring support.
+
+## Import source code
+
+In order to import the source code, follow instructions below:
+
+1. Press **File** > **Import** Menu item
+2. In new dialog Select **Maven** > **Existing Maven Projects**
+3. Press *Next*
+
+   ![Import existing projects into Eclipse](../eclipse-import-existing-projects.png)
+
+4. In **Select root directory** field enter the location of your source code:
+
+   * `C:\dev\geonetwork\trunk`
+
+5. Select All projects and Press **Finish** button.
+
+6. During the import process Eclipse will attempt to map each maven plugin to matching
+   functionality provided by the Eclipse IDE.
+
+   If another window appears showing these associations, just continue without changing any option.
+
+7. It will take some minutes while the m2e plugin downloads all the Maven dependencies.
+
+## Building
+
+The Eclispe IDE is configured to respect the `src` and `target` locations defined by the maven `pom.xml` file.
+
+* Eclipse makes use of an incremental compiler, allowing classes to be changed during debugging sessions.
+
+* If you build on the command line, be sure to run a clean build in Eclipse when switching back to the IDE.
+
+## Running with Jetty
+
+Use **Run As** > **Maven Build** to use `jetty:run` from inside Eclipse.
+
+You can add some maven variables to be able to run in parallel a debug watch to debug your code.
+
+## Debugging with 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>
+```
+
+## Debugging with Tomcat Server
+
+The Eclipse for [Web Tools Project](https://www.eclipse.org/webtools/) includes a
+Tomcat Plugin for controlling a Tomcat Service.
+
+#. 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)