sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1866081 - in /sis/site/trunk: content/index.mdtext content/source.mdtext templates/skeleton.html
Date Thu, 29 Aug 2019 15:23:00 GMT
Author: desruisseaux
Date: Thu Aug 29 15:22:59 2019
New Revision: 1866081

URL: http://svn.apache.org/viewvc?rev=1866081&view=rev
Log:
Rewrite the "Checkout source code" page with separated instruction for basic installation
and more advanced installation.

Modified:
    sis/site/trunk/content/index.mdtext
    sis/site/trunk/content/source.mdtext
    sis/site/trunk/templates/skeleton.html

Modified: sis/site/trunk/content/index.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/index.mdtext?rev=1866081&r1=1866080&r2=1866081&view=diff
==============================================================================
--- sis/site/trunk/content/index.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/index.mdtext [UTF-8] Thu Aug 29 15:22:59 2019
@@ -29,9 +29,9 @@ The SIS storage modules provide a common
 Some Apache SIS features are:
 
   * Geographic metadata (ISO 19115-1:2014)
-    * Read from or written to ISO 19115-3 compliant XML documents, or the previous version
(ISO 19139:2007).
+    * Read from or written to ISO 19115-3:2016 (current standard) or ISO 19139:2007 (older
standard) compliant XML documents.
     * Read from netCDF, GeoTIFF, Landsat, GPX and Moving Feature CSV encoding.
-    * Automatic conversions between the model published in 2003 and the revision published
in 2014.
+    * Automatic conversions between the metadata model published in 2003 and the revision
published in 2014.
   * Referencing by coordinates (ISO 19111:2007)
     * Well Known Text (WKT) version 1 and 2 (ISO 19162:2015).
     * Geographic Markup Language (GML) version 3.2 (ISO 19136:2007).

Modified: sis/site/trunk/content/source.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/source.mdtext?rev=1866081&r1=1866080&r2=1866081&view=diff
==============================================================================
--- sis/site/trunk/content/source.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/source.mdtext [UTF-8] Thu Aug 29 15:22:59 2019
@@ -1,4 +1,4 @@
-Title:  Source code
+Title:  Checkout source code
 Notice: Licensed to the Apache Software Foundation (ASF) under one
         or more contributor license agreements.  See the NOTICE file
         distributed with this work for additional information
@@ -17,96 +17,144 @@ Notice: Licensed to the Apache Software
         under the License.
 
 
-Apache SIS source code is maintained using [Git][git] version control.
-Additional data not included in SIS releases are maintained separately using [Subversion][subversion]
version control.
-Those data include in particular the [EPSG geodetic dataset](epsg.html) and are subject to
different licensing terms.
-The Git repository is [mirrored on GitHub][github-sis] and the non-free data can be [browsed
online][viewvc-non-free].
-For fetching the source code and those additional data, use the following commands:
+Apache SIS source code is maintained using [Git][git] version control,
+completed by optional data maintained using [Subversion][subversion] version control.
+Optional data include in particular the [EPSG geodetic dataset][epsg-install]
+and are subject to different licensing terms.
+This page describes two ways to checkout Apache SIS source code:
+
+  * A basic checkout with only the main repository, the most stable branch, and no configuration
required.
+  * A more advanced configuration for active SIS developments, using uncommitted (for now)
API
+    and including optional data for more extensive tests.
+
+It is possible to start with the basic checkout and migrate to the advanced configuration
later,
+or to cherry-pick only the interesting parts of the advanced configuration.
+
+[TOC]
+
+
+
+Basic installation    {#basic}
+==============================
+
+Create an empty directory for the Apache SIS project.
+We use `ApacheSIS` directory name in this page, but that name can be anything;
+replace that name in the shell commands below if another name is used.
+The Apache SIS source code will be cloned in that directory:
 
     :::bash
+    mkdir ApacheSIS
+    cd ApacheSIS
     git clone https://gitbox.apache.org/repos/asf/sis
-    svn checkout https://svn.apache.org/repos/asf/sis/data/non-free/
 
-The source code repository contains `geoapi-3.1` and `geoapi-4.0` branches in addition of
`master`.
-The Apache SIS releases are created from the code on `master` only.
-However the actual development occurs on the `geoapi-4.0` branch before to be merged to `master`.
-Those branches exist in order to experiment early new API and technologies — since it may
impact
-the library design — while keeping the releases compatible with officially released environments.
-The remaining of this page gives some guidelines about the way SIS source code is organized.
-
-[TOC]
+(note: [GitHub URL][github-sis] can be substituted to above Apache GitBox URL if desired.)
 
+At this stage, the `ApacheSIS` directory is redundant with the `sis` subdirectory.
+But we recommend to create that parent directory anyway in anticipation
+for more subdirectories to be created later, when desired.
 
+That is all. Apache SIS can be built by running `mvn install` in the `sis` subdirectory.
+The remaining of this page describes optional configurations for more advanced developments.
 
-Development branches    {#development}
-======================================
 
-Users who want stability are encouraged to build from the `master`.
-The master depends on GeoAPI 3.0.1,
-which is the [latest GeoAPI][geoapi-stable] released by the Open Geospatial Consortium (OGC).
-Developers who want to contribute to Apache SIS are encouraged to use the `geoapi-4.0` branch
for now.
 
+Advanced installation    {#advanced}
+====================================
 
+All sub-sections below are optional.
 
-GeoAPI 4.0 branch    {#geoapi-4.0}
-----------------------------------
 
-The `geoapi-4.0` branch is the recommended development branch for now.
-This branch implements the interfaces defined in GeoAPI 4.0 snapshot milestones.
-This branch uses new interfaces introduced in GeoAPI 4.0-SNAPSHOT and contains upgrades for
changes in existing GeoAPI interfaces.
-Some changes in GeoAPI 4.0-SNAPSHOT interfaces are incompatible with GeoAPI 3.0.1 interfaces.
-They are caused by changes in the underlying international standards, or by evolution of
Java technology.
-The content of this branch may be fully merged to `master` in the future, depending on new
GeoAPI releases from OGC.
+Create data directory    {#data}
+--------------------------------
 
+Apache SIS needs a directory where to store database, datum shift files and other optional
data.
+That directory is specified by the `SIS_DATA` environment variable and can be located anywhere.
+A convenient location is in a subdirectory of the `ApacheSIS` directory created in above
section.
+For example (with `ApacheSIS` as the current directory):
 
+    :::bash
+    mkdir Data
+    export SIS_DATA=$PWD/Data
 
-GeoAPI 3.1 branch    {#geoapi-3.1}
-----------------------------------
 
-The `geoapi-3.1` branch implements the interfaces defined in [GeoAPI 3.1 snapshot][geoapi-snapshot]
milestones.
-It has the same content that the `geoapi-4.0` branch, excluding changes that are incompatible
with GeoAPI 3.0.1.
-Developments happen on `geoapi-4.0` and are periodically merged to `geoapi-3.1` with the
necessary modifications.
-This branch is used merely as an intermediate step between the development branch (`geoapi-4.0`)
and `master`.
-Its content may be fully merged to `master` in the future, after new GeoAPI releases from
OGC.
+Checkout non-free data    {#non-free}
+-------------------------------------
 
+The EPSG geodetic dataset is recommended for operations related to Coordinate Reference Systems.
+Without the EPSG database, only a [small subset](apidocs/org/apache/sis/referencing/CRS.html#forCode-java.lang.String-)
+of coordinate reference systems can be created from EPSG codes.
+The EPSG database can be [installed in various ways][epsg-install],
+but this section describes an alternative way more suitable to Apache SIS development.
+Before to continue, make sure to agree with [EPSG terms of use][EPSG-ToU].
+Then following command can be executed with `ApacheSIS` as the current directory:
 
+    :::bash
+    # Executing this command imply agreement with EPSG terms of use.
+    svn checkout https://svn.apache.org/repos/asf/sis/data/non-free/
 
-Master    {#master}
--------------------
+Then copy or link the EPSG scripts in the directory where Apache SIS looks for optional data.
+Adjust the relative paths as needed if the `SIS_DATA` environment variable
+points to another location than the one used in above section:
 
-The master is a merge of `geoapi-3.1` branch ported to the interfaces defined by the [GeoAPI
stable release][geoapi-stable].
-This is the code which is built by the continuous integration system and deployed on the
Maven repository.
-**Commits on master can not be removed, since `git push --force` are not allowed on this
branch.**
-Commits should be pushed on above-cited development branch first,
-so they can be rearranged if needed before merge to `master`.
+    :::bash
+    mkdir $SIS_DATA/Databases
+    mkdir $SIS_DATA/Databases/ExternalSources
+    cd $SIS_DATA/Databases/ExternalSources
+    ln -s ../../../non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/Data.sql
   EPSG_Data.sql
+    ln -s ../../../non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/FKeys.sql
  EPSG_FKeys.sql
+    ln -s ../../../non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/Tables.sql
 EPSG_Tables.sql
+    cd -
+
+This is sufficient for allowing Apache SIS to create the geodetic database
+without the need for `sis-epsg` or `sis-embedded-data` module on the classpath.
+This setting is not done automatically because Apache projects can not introduce
+non-free dependencies without explicit action from user.
+If this action is not taken, some JUnit tests requiring EPSG data may be ignored
+(they will not cause the build to fail however).
+If any EPSG file is updated, deleting the `$SIS_DATA/Databases/SpatialMetadata` directory
+is sufficient for causing Apache SIS to recreate the Derby database with new data.
 
 
-### Code differences    {#differences}
+Configure PostgreSQL    {#postgres}
+-----------------------------------
 
-The main differences (apart version number) between `master` and `geoapi-3.1/4.0` branches
-are the modifications necessary for implementing an older version of GeoAPI interfaces.
-In particular, usages of non-released GeoAPI interfaces may be replaced
-by direct usages of the corresponding Apache SIS implementation classes.
 
-For security reasons and for avoiding misleading information, the following functionalities
are disabled on master for now
-(but are still enabled on branches as experimental features). In particular the `Supervisor.ENABLED`
flag controls
-whether the MBeans documented in the `org.apache.sis.console` package are enabled or not.
+Switch to GeoAPI 4.0 branch    {#geoapi-4.0}
+--------------------------------------------
 
-  * In `core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java`, the
`ENABLED` flag is set to `false`.
-  * In `core/sis-utility/src/main/java/org/apache/sis/internal/util/TemporalUtilities.java`,
the `REPORT_MISSING_MODULE` flag is set to `false`.
+The source code repository contains `geoapi-3.1` and `geoapi-4.0` branches in addition of
`master`.
+Apache SIS releases are created from code on `master` only, which depends on GeoAPI 3.0.1
+(the [latest GeoAPI release][geoapi-stable] from Open Geospatial Consortium).
+However the actual development occurs on the `geoapi-4.0` branch before to be merged to `master`.
+Those branches exist in order to experiment early new API and technologies — since it may
impact
+the library design — while keeping the releases compatible with officially released environments.
 
+  * The `geoapi-4.0` branch implements interfaces defined in GeoAPI 4.0 snapshot milestones.
+    Some changes in GeoAPI 4.0-SNAPSHOT interfaces are incompatible with GeoAPI 3.0.1 interfaces.
+    They are caused by changes in the underlying international standards, or by evolution
of Java technology.
+
+  * The `geoapi-3.1` branch implements interfaces defined in [GeoAPI 3.1 snapshot][geoapi-snapshot]
milestones.
+    It has the same content that the `geoapi-4.0` branch, excluding changes that are incompatible
with GeoAPI 3.0.1.
+    This branch is used merely as an intermediate step between the development branch (`geoapi-4.0`)
and `master`.
+
+  * The `master` branch is a merge of `geoapi-3.1` branch ported to the interfaces defined
by the [GeoAPI stable release][geoapi-stable].
+    This is the code which is built by the continuous integration system and deployed on
the Maven repository.
+    **Commits on master can not be removed, since `git push --force` are not allowed on this
branch.**
+    Commits should be pushed on above-cited development branch first,
+    so they can be rearranged if needed before merge to `master`.
 
-### Behavioral differences    {#behavior}
 
-Because of changes between GeoAPI 3.0 and GeoAPI 4.0-SNAPSHOT, the following aspects need
special care:
+The `geoapi` branches will hopefully be fully merged to `master` in the future, depending
on new GeoAPI releases from OGC.
+In the meantime, developer can switch to the most active development branch as below:
 
-  * If `op` is an instance of `PassThroughOperation`, then the `if (op instanceof SingleOperation)`
expression
-    evaluates to `true` on master but to `false` on SIS development branches.
+    :::bash
+    cd sis
+    git checkout geoapi-4.0
 
 
 
 History    {#history}
----------------------
+=====================
 
 All developments and tags prior Apache SIS 1.0 were done on a [Subversion][subversion] repository
 and can be [browsed online][viewvc].
@@ -176,11 +224,12 @@ then execute the following steps:
 *[ISO]: International Organization for Standardization
 *[OGC]: Open Geospatial Consortium
 
-[viewvc]:           http://svn.apache.org/viewvc/sis/
-[viewvc-non-free]:  http://svn.apache.org/viewvc/sis/data/non-free/
 [subversion]:       http://subversion.apache.org
 [git]:              http://git-scm.com
 [github-sis]:       https://github.com/apache/sis
+[viewvc]:           http://svn.apache.org/viewvc/sis/
+[epsg-install]:     epsg.html
+[EPSG-ToU]:         http://www.epsg.org/TermsOfUse.aspx
 [svn-sis-tags]:     https://svn.apache.org/repos/asf/sis/tags/
 [geoapi-stable]:    http://www.geoapi.org/3.0/index.html
 [geoapi-snapshot]:  http://www.geoapi.org/snapshot/index.html

Modified: sis/site/trunk/templates/skeleton.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/templates/skeleton.html?rev=1866081&r1=1866080&r2=1866081&view=diff
==============================================================================
--- sis/site/trunk/templates/skeleton.html (original)
+++ sis/site/trunk/templates/skeleton.html Thu Aug 29 15:22:59 2019
@@ -32,10 +32,11 @@
               </li>
               <li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project
Documentation<b class="caret"></b></a>
                 <ul class="dropdown-menu">
-                  <li><a href="book/index.html">Developer guide</a></li>
+                  <li><a href="book/index.html">Developer Guide</a></li>
                   <li><a href="apidocs/index.html">Online Javadoc</a></li>
                   <li><a href="downloads.html">Downloads</a></li>
-                  <li><a href="source.html">Source Code</a></li>
+                  <li><a href="source.html">Checkout Sources</a></li>
+                  <li><a href="epsg.html">EPSG Database</a></li>
                   <li><a href="faq.html">FAQ</a></li>
                   <li><a href="https://issues.apache.org/jira/browse/SIS">Issue
Tracker</a></li>
                 </ul>
@@ -69,10 +70,11 @@
               <li><a href="mail-lists.html">Mailing Lists</a></li>
               <li><a href="team-list.html">Project Team</a></li>
               <li class="nav-header">Project Documentation</li>
-              <li><a href="book/index.html">Developer guide</a></li>
+              <li><a href="book/index.html">Developer Guide</a></li>
               <li><a href="apidocs/index.html">Online Javadoc</a></li>
               <li><a href="downloads.html">Downloads</a></li>
-              <li><a href="source.html">Source Code</a></li>
+              <li><a href="source.html">Checkout Sources</a></li>
+              <li><a href="epsg.html">EPSG Database</a></li>
               <li><a href="faq.html">FAQ</a></li>
               <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
               <li class="nav-header">ASF</li>



Mime
View raw message