sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1031597 - in /websites/staging/sis/trunk/content: ./ branches.html index.html source.html
Date Fri, 22 Jun 2018 09:43:33 GMT
Author: buildbot
Date: Fri Jun 22 09:43:33 2018
New Revision: 1031597

Log:
Staging update by buildbot for sis

Removed:
    websites/staging/sis/trunk/content/branches.html
Modified:
    websites/staging/sis/trunk/content/   (props changed)
    websites/staging/sis/trunk/content/index.html
    websites/staging/sis/trunk/content/source.html

Propchange: websites/staging/sis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Jun 22 09:43:33 2018
@@ -1 +1 @@
-1834085
+1834088

Modified: websites/staging/sis/trunk/content/index.html
==============================================================================
--- websites/staging/sis/trunk/content/index.html (original)
+++ websites/staging/sis/trunk/content/index.html Fri Jun 22 09:43:33 2018
@@ -153,9 +153,8 @@ However a command-line tool is provided
 <p>Following links are for those who wish to contribute to Apache SIS:</p>
 <ul>
 <li><a href="contributor.html">New contributor</a>: background knowledge.</li>
-<li><a href="source.html">Source code</a>: fetching the code, opening in
an IDE, formatting.</li>
+<li><a href="source.html">Source code</a>: fetching the code, choosing
a branches, opening in an IDE, formatting.</li>
 <li><a href="build.html">Build</a>: build from the source, create the PACK200
file.</li>
-<li><a href="branches.html">Branches</a>: master, geoapi-3.1, geoapi-4.0</li>
 <li><a href="http://issues.apache.org/jira/browse/SIS">Issue tracking</a>:
JIRA.</li>
 <li><a href="release-management.html">Release management</a> (for release
managers)</li>
 <li><a href="site-management.html">Web site management</a> (for release
managers and site maintainers)</li>

Modified: websites/staging/sis/trunk/content/source.html
==============================================================================
--- websites/staging/sis/trunk/content/source.html (original)
+++ websites/staging/sis/trunk/content/source.html Fri Jun 22 09:43:33 2018
@@ -100,24 +100,44 @@
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover
> .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink
{ visibility: visible }</style>
 <p>Apache SIS source code is maintained using <a href="http://git-scm.com">Git</a>
version control.
 For fetching the source code, use the following commands:</p>
-<div class="codehilite"><pre>git clone https://gitbox.apache.org/repos/asf/sis.git
+<div class="codehilite"><pre>git clone https://gitbox.apache.org/repos/asf/sis
 </pre></div>
 
 
 <p>The above Git repository is mirrored on GitHub at <a href="https://github.com/apache/sis">https://github.com/apache/sis</a>.
-Note that the git repository does not include the non-free data (in particular the <a
href="epsg.html">EPSG geodetic dataset</a>).
+Note that the git repository does not include the non-free data, in particular the <a
href="epsg.html">EPSG geodetic dataset</a>.
 Those data are currently provided only on Subversion repository.</p>
+<p>The source code repository contains <code>geoapi-3.1</code> and <code>geoapi-4.0</code>
branches in addition of <code>master</code>.
+The Apache SIS releases are created from the code on <code>master</code> only.
+However the actual development occurs on the <code>geoapi-4.0</code> branch before
to be merged to <code>master</code>.
+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.</p>
 <p>The remaining of this page gives some guidelines about the way SIS source code is
organized.</p>
 <div class="toc">
 <ul>
+<li><a href="#development">Development branches</a><ul>
+<li><a href="#geoapi-4.0">GeoAPI 4.0 branch</a></li>
+<li><a href="#geoapi-3.1">GeoAPI 3.1 branch</a></li>
+<li><a href="#master">Master</a><ul>
+<li><a href="#differences">Code differences</a></li>
+<li><a href="#behavior">Behavioral differences</a></li>
+</ul>
+</li>
+</ul>
+</li>
 <li><a href="#ide">Opening Apache SIS in an IDE</a><ul>
 <li><a href="#netbeans">NetBeans</a></li>
 <li><a href="#eclipse">Eclipse</a></li>
 </ul>
 </li>
 <li><a href="#license">License header</a></li>
-<li><a href="#naming">Naming convention</a></li>
+<li><a href="#naming">Naming convention</a><ul>
+<li><a href="#internal">Internal packages</a></li>
+<li><a href="#substitutions">Substitution for non-existent classes</a></li>
+</ul>
+</li>
 <li><a href="#formatting">Code formatting</a><ul>
+<li><a href="#imports">Import statements</a></li>
 <li><a href="#spaces">Spaces and line length</a></li>
 <li><a href="#brackets">Brackets</a></li>
 <li><a href="#declarations">Member declarations</a></li>
@@ -136,9 +156,51 @@ Those data are currently provided only o
 </li>
 </ul>
 </div>
+<h1 id="development">Development branches<a class="headerlink" href="#development"
title="Permanent link">&para;</a></h1>
+<p>Users who want stability are encouraged to build from the <code>master</code>.
+The master depends on GeoAPI 3.0.1,
+which is the <a href="http://www.geoapi.org/3.0/index.html">latest GeoAPI</a>
released by the Open Geospatial Consortium (<abbr title="Open Geospatial Consortium">OGC</abbr>).
+Developers who want to contribute to Apache SIS are encouraged to use the <code>geoapi-4.0</code>
branch for now.</p>
+<h2 id="geoapi-4.0">GeoAPI 4.0 branch<a class="headerlink" href="#geoapi-4.0" title="Permanent
link">&para;</a></h2>
+<p>The <code>geoapi-4.0</code> 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 <code>master</code> in the
future, depending on new GeoAPI releases from <abbr title="Open Geospatial Consortium">OGC</abbr>.</p>
+<h2 id="geoapi-3.1">GeoAPI 3.1 branch<a class="headerlink" href="#geoapi-3.1" title="Permanent
link">&para;</a></h2>
+<p>The <code>geoapi-3.1</code> branch implements the interfaces defined
in <a href="http://www.geoapi.org/snapshot/index.html">GeoAPI 3.1 snapshot</a>
milestones.
+It has the same content that the <code>geoapi-4.0</code> branch, excluding changes
that are incompatible with GeoAPI 3.0.1.
+Developments happen on <code>geoapi-4.0</code> and are periodically merged to
<code>geoapi-3.1</code> with the necessary modifications.
+This branch is used merely as an intermediate step between the development branch (<code>geoapi-4.0</code>)
and <code>master</code>.
+Its content may be fully merged to <code>master</code> in the future, after new
GeoAPI releases from <abbr title="Open Geospatial Consortium">OGC</abbr>.</p>
+<h2 id="master">Master<a class="headerlink" href="#master" title="Permanent link">&para;</a></h2>
+<p>The master is a merge of <code>geoapi-3.1</code> branch ported to the
interfaces defined by the <a href="http://www.geoapi.org/3.0/index.html">GeoAPI stable
release</a>.
+This is the code which is built by the continuous integration system and deployed on the
Maven repository.
+<strong>Commits on master can not be removed, since <code>git push --force</code>
are not allowed on this branch.</strong>
+Commits should be pushed on above-cited development branch first,
+so they can be rearranged if needed before merge to <code>master</code>.</p>
+<h3 id="differences">Code differences<a class="headerlink" href="#differences" title="Permanent
link">&para;</a></h3>
+<p>The main differences (apart version number) between <code>master</code>
and <code>geoapi-3.1/4.0</code> 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.</p>
+<p>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 <code>Supervisor.ENABLED</code>
flag controls
+whether the MBeans documented in the <code>org.apache.sis.console</code> package
are enabled or not.</p>
+<ul>
+<li>In <code>core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java</code>,
the <code>ENABLED</code> flag is set to <code>false</code>.</li>
+<li>In <code>core/sis-utility/src/main/java/org/apache/sis/internal/util/TemporalUtilities.java</code>,
the <code>REPORT_MISSING_MODULE</code> flag is set to <code>false</code>.</li>
+</ul>
+<h3 id="behavior">Behavioral differences<a class="headerlink" href="#behavior" title="Permanent
link">&para;</a></h3>
+<p>Because of changes between GeoAPI 3.0 and GeoAPI 4.0-SNAPSHOT, the following aspects
need special care:</p>
+<ul>
+<li>If <code>op</code> is an instance of <code>PassThroughOperation</code>,
then the <code>if (op instanceof SingleOperation)</code> expression
+    evaluates to <code>true</code> on master but to <code>false</code>
on SIS development branches.</li>
+</ul>
 <h1 id="ide">Opening Apache SIS in an IDE<a class="headerlink" href="#ide" title="Permanent
link">&para;</a></h1>
 <p>Different SIS branches are available depending on the GeoAPI versions.
-The alternatives are listed in the <a href="branches.html">branches page</a>.
+The alternatives are listed in <a href="#development">above section</a>.
 One thing to take in consideration can be summarized as below:</p>
 <ul>
 <li>There is no need to build GeoAPI prior working on SIS master.</li>
@@ -192,18 +254,48 @@ as below:</p>
 
 
 <h1 id="naming">Naming convention<a class="headerlink" href="#naming" title="Permanent
link">&para;</a></h1>
-<p>Implementations of GeoAPI interfaces usually (but not always) begin with <code>Abstract</code>,
<code>Default</code>, <code>Simple</code> or <code>General</code>
prefixes.</p>
+<p>Classes that do not implement an interface are usually not prefixed, even if abstract.
+Classes implementing GeoAPI interfaces usually (but not always) begin with <code>Abstract</code>,
<code>Default</code>, <code>Simple</code> or <code>General</code>
prefix.</p>
 <ul>
 <li>The <code>Abstract</code> prefix is used when a class is abstract according
<abbr title="International Organization for Standardization">ISO</abbr> specifications
— it may or may not be be abstract in the Java sense.</li>
 <li>The <code>General</code> 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.</li>
 <li>Implementations specialized for a fixed number of dimensions are suffixed with
<code>1D</code>, <code>2D</code>, <code>3D</code> or <code>4D</code>
rather than being prefixed.</li>
 </ul>
-<p>Classes that do not implement an interface are usually not prefixed, even if abstract.</p>
+<p>Example: <code>GeneralEnvelope</code> class is an implementation of
<code>Envelope</code> interface for the multi-dimensional case.
+<code>Envelope2D</code> is another implementation of the same interface specialized
for the two-dimensional case.</p>
+<h2 id="internal">Internal packages<a class="headerlink" href="#internal" title="Permanent
link">&para;</a></h2>
+<p>All classes in <code>org.apache.sis.internal</code> 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.</p>
+<h2 id="substitutions">Substitution for non-existent classes<a class="headerlink"
href="#substitutions" title="Permanent link">&para;</a></h2>
+<p>When using a JDK 9 class that does not exist on JDK 8, define a class of the same
name in a
+<code>org.apache.sis.internal</code> 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.</p>
 <h1 id="formatting">Code formatting<a class="headerlink" href="#formatting" title="Permanent
link">&para;</a></h1>
 <p>Apache SIS uses the standard Java conventions, except for the 80 characters line
length restriction.
 The conventions listed below are guidelines. Some exceptions to those conventions can occur
but should
 be rare (see <a href="#tabular-formatting">exceptions to coding conventions</a>).</p>
+<p>For making merges between branches easier, refrain from doing massive code reformatting
unless:</p>
+<ul>
+<li>the modified files do not yet exist on the other branches;</li>
+<li>or the modified lines are known to be identical on all active branches (merges
work well in such cases);</li>
+<li>or the committer is willing to resolve the merge conflicts.</li>
+</ul>
+<h2 id="imports">Import statements<a class="headerlink" href="#imports" title="Permanent
link">&para;</a></h2>
+<p>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:</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">java.io.File</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">java.util.List</span><span
class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.opengis.metadata.Metadata</span><span
class="o">;</span>
+
+<span class="c1">// Branch-specific imports</span>
+<span class="kn">import</span> <span class="nn">org.opengis.feature.Feature</span><span
class="o">;</span>
+</pre></div>
+
+
 <h2 id="spaces">Spaces and line length<a class="headerlink" href="#spaces" title="Permanent
link">&para;</a></h2>
 <ul>
 <li><strong>Indentation:</strong> Use a consistent space indents and never
use tabs.<ul>



Mime
View raw message