contributing

docs/manual/docs/contributing/doing-a-release.md

@@ -0,0 +1,208 @@
+# Doing a GeoNetwork release {#doing-a-release}
+
+This section documents the steps followed by the development team to do a new release.
+
+Once the release branch has been thoroughly tested and is stable a release can be made.
+
+1.  Prepare the release
+
+    ``` shell
+    # Setup properties
+    frombranch=origin/main
+    versionbranch=4.2.x
+    version=4.2.3
+    minorversion=0
+    newversion=$version-$minorversion
+    currentversion=4.2.3-SNAPSHOT
+    previousversion=4.2.2
+    nextversion=4.2.4-SNAPSHOT
+    nextMajorVersion=4.4.0-SNAPSHOT
+
+
+    # Get the branch
+    git clone --recursive https://github.com/geonetwork/core-geonetwork.git \
+              geonetwork-$versionbranch
+    cd geonetwork-$versionbranch
+
+
+    # Create or move to the branch for the version
+    # Create it if it does not exist yet
+    git checkout -b $versionbranch $frombranch
+    # or move into it if it exist
+    # git checkout $versionbranch
+    # or stay in main branch if the release is on main
+
+
+    # Update version number (in pom.xml, installer config and SQL)
+    ./update-version.sh $currentversion $newversion
+
+    # Generate list of changes
+    cat <<EOF > docs/changes$newversion.txt
+    ================================================================================
+    ===
+    === GeoNetwork $version: List of changes
+    ===
+    ================================================================================
+    EOF
+    git log --pretty='format:- %s' $previousversion... >> docs/changes$newversion.txt
+    ```
+
+2.  Commit & tag the new version
+
+    ``` shell
+    # Then commit the new version
+    git add .
+    git commit -m "Update version to $newversion"
+
+    # Create the release tag
+    git tag -a $version -m "Tag for $version release"
+    ```
+
+3.  Build
+
+    ``` shell
+    # Build the new release
+    mvn clean install -DskipTests -Pwar -Pwro4j-prebuild-cache
+
+
+    # Download Jetty and create the installer
+    cd release
+    mvn clean install -Djetty-download
+    ant
+
+
+    # Deploy to osgeo repository (requires credentials in ~/.m2/settings.xml)
+    mvn deploy
+    ```
+
+4.  Test
+
+    ``` shell
+    cd target/GeoNetwork-$newversion
+    unzip geonetwork-bundle-$newversion.zip -d geonetwork-bundle-$newversion
+    cd geonetwork-bundle-$newversion/bin
+    ./startup.sh -f
+    ```
+
+5.  Set the next version
+
+    ``` shell
+    # Set version number to SNAPSHOT
+    ./update-version.sh $newversion $nextversion
+
+    # Add SQL migration step for the next version
+    mkdir web/src/main/webapp/WEB-INF/classes/setup/sql/migrate/v424
+    cat <<EOF > web/src/main/webapp/WEB-INF/classes/setup/sql/migrate/v424/migrate-default.sql
+    UPDATE Settings SET value='4.2.4' WHERE name='system/platform/version';
+    UPDATE Settings SET value='SNAPSHOT' WHERE name='system/platform/subVersion';
+    EOF
+    vi web/src/main/webResources/WEB-INF/config-db/database_migration.xml
+    ```
+
+    In `WEB-INF/config-db/database_migration.xml` add an entry for the new version in the 2 steps:
+
+    ``` xml
+    <entry key="3.12.2">
+      <list>
+        <value>WEB-INF/classes/setup/sql/migrate/v3122/migrate-</value>
+      </list>
+    </entry>
+    ```
+
+    ``` shell
+    git add .
+    git commit -m "Update version to $nextversion"
+    ```
+
+6.  Publishing
+
+    ``` shell
+    # Push the branch and tag
+    git push origin $versionbranch
+    git push origin $version
+    ```
+
+7.  Generate checksum files
+
+    -   If using Linux:
+
+        ``` shell
+        cd web/target && md5sum geonetwork.war > geonetwork.war.md5 && cd ../..
+        cd release/target/GeoNetwork-$version && md5sum geonetwork-bundle-$newversion.zip >  geonetwork-bundle-$newversion.zip.md5 && cd ../../..
+        ```
+
+    -   If using Mac OS X:
+
+        ``` shell
+        md5 -r web/target/geonetwork.war > web/target/geonetwork.war.md5
+        md5 -r release/target/GeoNetwork-$newversion/geonetwork-bundle-$newversion.zip > release/target/GeoNetwork-$newversion/geonetwork-bundle-$newversion.zip.md5
+        ```
+
+    On sourceforge first:
+
+    ``` shell
+    sftp $sourceforge_username,[email protected]
+    # For stable release
+    cd /home/frs/project/g/ge/geonetwork/GeoNetwork_opensource
+    # or for RC release
+    cd /home/frs/project/g/ge/geonetwork/GeoNetwork_unstable_development_versions/
+    mkdir v3.12.1
+    cd v3.12.1
+    put docs/changes3.12.1-0.txt
+    put release/target/GeoNetwork*/geonetwork-bundle*.zip*
+    put web/target/geonetwork.war*
+    bye
+    ```
+
+8.  Update or add the changelog in the documentation <https://github.com/geonetwork/doc> .
+
+9.  Close the milestone on github <https://github.com/geonetwork/core-geonetwork/milestones?state=closed> with link to sourceforge download.
+
+    Publish the release on github <https://github.com/geonetwork/core-geonetwork/releases> .
+
+    Update the website links <https://github.com/geonetwork/website> .
+
+    -   Add the changes file for the release to <https://github.com/geonetwork/doc/tree/develop/source/overview/change-log>
+    -   List the previous file in <https://github.com/geonetwork/doc/blob/develop/source/overview/change-log/index.rst>
+    -   Update the version: <https://github.com/geonetwork/website/blob/master/docsrc/conf.py>
+    -   Update the download link: <https://github.com/geonetwork/website/blob/master/docsrc/downloads.rst>
+    -   Add the section for the new release: <https://github.com/geonetwork/website/blob/master/docsrc/news.rst>
+
+    Send an email to the mailing lists.
+
+10. Merge in depending branches
+
+    If a major version, then master version has to be updated to the next one (eg. if 3.8.0, then 3.7.x is 3.9.x).
+
+    ``` shell
+    # Create it if it does not exist yet
+    git checkout master
+    ./update-version.sh $currentversion $nextMajorVersion
+    ```
+
+    In the following folder `web/src/main/webapp/WEB-INF/classes/setup/sql/migrate` create `v370` folder.
+
+    In this folder create a `migrate-default.sql` with the following content:
+
+    ``` sql
+    UPDATE Settings SET value='3.7.0' WHERE name='system/platform/version';
+    UPDATE Settings SET value='SNAPSHOT' WHERE name='system/platform/subVersion';
+    ```
+
+    In `web/src/main/webResources/WEB-INF/config-db/database_migration.xml` add the following for the migration to call the migration script:
+
+    ``` xml
+    <entry key="3.7.0">
+      <list>
+        <value>WEB-INF/classes/setup/sql/migrate/v370/migrate-</value>
+      </list>
+    </entry>
+    ```
+
+    Commit the new version
+
+    ``` shell
+    git add .
+    git commit -m "Update version to $nextMajorVersion"
+    git push origin master
+    ```

docs/manual/docs/contributing/index.md

@@ -0,0 +1,9 @@
+# Contributing guide
+
+The guide for people who want to contribute to GeoNetwork.
+
+-   [Writing Documentation](writing-documentation.md)
+-   [Style Guide](style-guide.md)
+-   [Translating](translating.md)
+-   [Making A Pull Request](making-a-pull-request.md)
+-   [Doing A Release](doing-a-release.md)

docs/manual/docs/contributing/making-a-pull-request.md

@@ -0,0 +1,49 @@
+# Making a pull request
+
+GeoNetwork uses a pull-request workflow allowing changes to be managed and reviewed. All work is done on branches and merged back. When developing start with the branch you want changed, create a new feature branch from there, make your changes on the feature branch, publish your feature branch to your GitHub repo, make a Pull Request asking your changes to be reviewed and merged.
+
+Occasionally core GeoNetwork developers will setup a feature branch on upstream to explore a specific topic. These shared feature-branch are subject to review when submitted as a pull-request against `master`.
+
+There are many great guides (See the links above) but here is a quick sequence illustrating how to make a change and commit the change.
+
+``` shell
+$ git checkout master
+   # master is the 'trunk' and main development branch
+   # the checkout command "checks out" the requested branch
+
+$ git checkout -b myfeature
+   # the -b requests that the branch be created
+   # ``git branch`` will list all the branches you have checked out locally at some point
+   # ``git branch -a`` will list all branches in repository (checked out or not)
+
+# work work work
+
+$ git status
+   # See what files have been modified or added
+
+$ git add <new or modified files>
+   # Add all files to be committed ``git add -u`` will add all modified (but not untracked)
+
+$ git commit -m "<a short message describing change>"
+   # Commit often.  it is VERY fast to commit
+   # NOTE: doing a commit is a local operation.  It does not push the change to Github
+
+# more work
+# another commit
+
+$ git push origin myfeature
+
+   # this pushed your new branch to Github
+   # now you are ready to make a Pull Request to get the new feature added to GeoNetwork
+
+# revise pull request based on review feedback
+# another commit
+# another push to update pull request
+# Success!!
+```
+
+GeoNetwork uses git submodules in order to keep track of externals dependencies. It is necessary to init and update them after a branch change:
+
+``` shell
+git submodule update --init
+```

docs/manual/docs/contributing/style-guide.md

@@ -0,0 +1,10 @@
+# Style Guide
+
+This is a work-in-progress style guide to help creating consistent documentation for GeoNetwork.
+
+## Preferred Terminology
+
+> -   Catalog Home Page
+> -   GeoNetwork (check capitalisation, or preferably use the `GeoNetwork` variable)
+> -   Metadata Catalog
+> -   Sub-Portal

docs/manual/docs/contributing/translating.md

@@ -0,0 +1,75 @@
+# Translating the application {#translating}
+
+To translate the client interface, go on [GeoNetwork on Transifex](https://www.transifex.com/geonetwork/core-geonetwork/). Only the reference language (ie. en) MUST be updated on github. All other translations MUST be on Transifex.
+
+Main files to translate are the `Angular UI` ones:
+
+![](img/transifex.png)
+
+Once translated, the new language needs to be added to the application.
+
+-   Add the files to the client application in `web-ui/src/main/resources/catalog/locales`
+-   Register the new lang in `web-ui/src/main/resources/catalog/js/CatController.js`
+
+``` js
+// Add the language here
+module.constant('gnLangs', {
+  langs: {
+    'eng': 'en',
+    'dut': 'du',
+    'fre': 'fr',
+    'ger': 'ge',
+    'kor': 'ko',
+    'spa': 'es',
+    'cze': 'cz'
+  },
+
+
+// Lang names to be displayed in language selector
+$scope.langLabels = {'eng': 'English', 'dut': 'Nederlands',
+  'fre': 'Français', 'ger': 'Deutsch', 'kor': '한국의',
+  'spa': 'Español', 'cze': 'Czech'};
+```
+
+To automatically retrieve and update translations files, the script `web-ui/download-from-transifex.sh` can be used. To use the script you have to join the translation team on Transifex.
+
+Register the new lang in the l variable of the transifex synchronization file:
+
+``` shell
+SRC_DIR=src/main/resources/catalog/locales
+
+l=(
+    'es::es'
+    'fr::fr'
+    'cz::cz'
+```
+
+and run the script
+
+``` shell
+cd web-ui
+./download-from-transifex.sh
+```
+
+Then on the Java application, register the new language in `src/main/webResources/WEB-INF/config-spring-geonetwork.xml`:
+
+``` xml
+<util:set id="languages">
+  <value>ara</value>
+  <value>cze</value>
+```
+
+Add a new SQL file for the database initialization in `src/main/webapp/WEB-INF/classes/setup/sql/data/loc-cze-default.sql` and update translations. This file is used to register the new language for database entity translations (eg. groups, status).
+
+In `src/main/webResources/WEB-INF/config-db/initial_data.xml`, register the new SQL file:
+
+``` xml
+<bean class="org.fao.geonet.domain.Pair" factory-method="read">
+  <constructor-arg value="WEB-INF/classes/setup/sql/data"/>
+  <constructor-arg value="loc-cze-"/>
+</bean>
+```
+
+# Translating a standard
+
+To translate a standard, see the schema folder (`schemas/iso19139/src/main/plugin/iso19139/loc`). Those files are used in the editor and formatters to translate standard elements, to provide help text, recommended values list, \...