Author: desruisseaux
Date: Fri Jun 22 09:43:23 2018
New Revision: 1834088
URL: http://svn.apache.org/viewvc?rev=1834088&view=rev
Log:
Merge the branches page with the source code page.
Removed:
sis/site/trunk/content/branches.mdtext
Modified:
sis/site/trunk/content/index.mdtext
sis/site/trunk/content/source.mdtext
Modified: sis/site/trunk/content/index.mdtext
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/index.mdtext?rev=1834088&r1=1834087&r2=1834088&view=diff
==============================================================================
--- sis/site/trunk/content/index.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/index.mdtext [UTF-8] Fri Jun 22 09:43:23 2018
@@ -72,9 +72,8 @@ Apache SIS developer documentation {#
Following links are for those who wish to contribute to Apache SIS:
* [New contributor](contributor.html): background knowledge.
- * [Source code](source.html): fetching the code, opening in an IDE,
formatting.
+ * [Source code](source.html): fetching the code, choosing a branches,
opening in an IDE, formatting.
* [Build](build.html): build from the source, create the PACK200 file.
- * [Branches](branches.html): master, geoapi-3.1, geoapi-4.0
* [Issue tracking][JIRA]: JIRA.
* [Release management](release-management.html) (for release managers)
* [Web site management](site-management.html) (for release managers and site
maintainers)
Modified: sis/site/trunk/content/source.mdtext
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/source.mdtext?rev=1834088&r1=1834087&r2=1834088&view=diff
==============================================================================
--- sis/site/trunk/content/source.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/source.mdtext [UTF-8] Fri Jun 22 09:43:23 2018
@@ -21,23 +21,96 @@ Apache SIS source code is maintained usi
For fetching the source code, use the following commands:
:::bash
- git clone https://gitbox.apache.org/repos/asf/sis.git
+ git clone https://gitbox.apache.org/repos/asf/sis
The above Git repository is mirrored on GitHub at
[https://github.com/apache/sis](https://github.com/apache/sis).
-Note that the git repository does not include the non-free data (in particular
the [EPSG geodetic dataset](epsg.html)).
+Note that the git repository does not include the non-free data, in particular
the [EPSG geodetic dataset](epsg.html).
Those data are currently provided only on Subversion repository.
+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]
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+Master {#master}
+-------------------
+
+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`.
+
+
+### Code differences {#differences}
+
+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.
+
+ * 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`.
+
+
+### Behavioral differences {#behavior}
+
+Because of changes between GeoAPI 3.0 and GeoAPI 4.0-SNAPSHOT, the following
aspects need special care:
+
+ * 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.
+
+
+
Opening Apache SIS in an IDE {#ide}
======================================
Different SIS branches are available depending on the GeoAPI versions.
-The alternatives are listed in the [branches page](branches.html).
+The alternatives are listed in [above section](#development).
One thing to take in consideration can be summarized as below:
* There is no need to build GeoAPI prior working on SIS master.
@@ -110,17 +183,37 @@ as below:
Naming convention {#naming}
==============================
-Implementations of GeoAPI interfaces usually (but not always) begin with
`Abstract`, `Default`, `Simple` or `General` prefixes.
+Classes that do not implement an interface are usually not prefixed, even if
abstract.
+Classes implementing GeoAPI interfaces usually (but not always) begin with
`Abstract`, `Default`, `Simple` or `General` prefix.
* The `Abstract` prefix is used when a class is abstract according ISO
specifications — it may or may not be be abstract in the Java sense.
* The `General` prefix is used when an implementation is designed for use in
the general case,
as opposed to other implementations specialized for a fixed number of
dimensions or other conditions.
* Implementations specialized for a fixed number of dimensions are suffixed
with `1D`, `2D`, `3D` or `4D` rather than being prefixed.
-Classes that do not implement an interface are usually not prefixed, even if
abstract.
+Example: `GeneralEnvelope` class is an implementation of `Envelope` interface
for the multi-dimensional case.
+`Envelope2D` is another implementation of the same interface specialized for
the two-dimensional case.
+Internal packages {#internal}
+--------------------------------
+
+All classes in `org.apache.sis.internal` sub-packages are for SIS usage only
and may change without warning in any future release.
+Those classes are excluded from Javadoc and will not be exported by SIS Jigsaw
modules.
+Those packages may be renamed after SIS upgraded to JDK 9.
+
+
+
+Substitution for non-existent classes {#substitutions}
+---------------------------------------------------------
+
+When using a JDK 9 class that does not exist on JDK 8, define a class of the
same name in a
+`org.apache.sis.internal` sub-package with the minimal amount of needed
functionalities,
+provided that it can be done with reasonable effort.
+Otherwise just delete the JDK9-dependent code from the development branch.
+
+
Code formatting {#formatting}
================================
@@ -129,6 +222,29 @@ Apache SIS uses the standard Java conven
The conventions listed below are guidelines. Some exceptions to those
conventions can occur but should
be rare (see [exceptions to coding conventions](#tabular-formatting)).
+For making merges between branches easier, refrain from doing massive code
reformatting unless:
+
+ * the modified files do not yet exist on the other branches;
+ * or the modified lines are known to be identical on all active branches
(merges work well in such cases);
+ * or the committer is willing to resolve the merge conflicts.
+
+
+
+Import statements {#imports}
+-------------------------------
+
+Isolate at the end of the imports section any import statements that are
specific to a platform.
+This separation allows any branch to re-arrange the common import statements
without generating
+conflicts with the platform-dependent import statements. Example:
+
+ :::java
+ import java.io.File;
+ import java.util.List;
+ import org.opengis.metadata.Metadata;
+
+ // Branch-specific imports
+ import org.opengis.feature.Feature;
+
Spaces and line length {#spaces}
@@ -297,3 +413,5 @@ Note that a [JavaScript display engine][
[mathml-fonts]:
http://developer.mozilla.org/en-US/docs/Mozilla/MathML_Project/Fonts
[mathml-plugin-ie]: http://www.dessci.com/en/products/mathplayer/download.htm
[mathml-mathjax]: http://www.mathjax.org/
+[geoapi-stable]: http://www.geoapi.org/3.0/index.html
+[geoapi-snapshot]: http://www.geoapi.org/snapshot/index.html
