Documentation about writing docs.

geoawd · May 4, 2015 · 3fb38e0 · 3fb38e0
1 parent 54e36ed
commit 3fb38e0
Show file tree

Hide file tree

Showing 9 changed files with 390 additions and 4 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+target
diff --git a/en/conf.py b/en/conf.py
@@ -31,6 +31,7 @@
 # ones.
 extensions = [
     'sphinx.ext.todo',
+    'sphinx.ext.extlinks',
     'sphinx.ext.ifconfig',
 ]
 
@@ -277,9 +278,13 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  (master_doc, 'GeoNetworkopensource', u'GeoNetwork opensource Documentation',
-   author, 'GeoNetworkopensource', 'One line description of project.',
-   'Miscellaneous'),
+  (master_doc,
+  'GeoNetworkopensource',
+  u'GeoNetwork opensource Documentation',
+  author,
+  'GeoNetworkopensource',
+  'One line description of project.',
+  'Miscellaneous')
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -293,3 +298,22 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+extlinks = {
+ 'issue': ('https://github.com/geonetwork/core-geonetwork/issues/%s', 'issue #'),
+ 'pr': ('https://github.com/geonetwork/core-geonetwork/pull/%s', 'pull request #'),
+ 'code': ('https://github.com/geonetwork/core-geonetwork/tree/develop/%s', 'source file '),
+ 'repo': ('https://github.com/geonetwork/%s', 'code repository '),
+ 'wiki': ('https://github.com/geonetwork/core-geonetwork/wiki/%s', 'wiki page ')
+}
+
+rst_epilog = """
+.. |project_name| replace:: GeoNetwork
+.. |project_url| replace:: http://geonetwork-opensource.org
+.. |jdbc.properties| replace:: ``WEB-INF/config-db/jdbc.properties``
+.. |config.node.folder| replace:: ``WEB-INF/config-node``
+.. |default.node| replace:: ``srv``
+.. |default.node.config.file| replace:: ``WEB-INF/config-node/srv.xml``
+.. |install.homepage| replace:: your installation
+.. _install.homepage: http://localhost:8080/geonetwork
+"""
diff --git a/en/contributing/doing-a-release.rst b/en/contributing/doing-a-release.rst
@@ -0,0 +1,159 @@
+.. _doing-a-release:
+
+
+Doing a |project_name| 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.
+
+
+#. Get the branch
+
+.. code-block:: shell
+
+    versionbranch=3.0.x
+    version=3.0.0
+    minorversion=0
+    newversion=$version-$minorversion
+    currentversion=3.0.0-SNAPSHOT
+    previousversion=2.10.x
+    modules=( "geoserver" "e2e-tests" )
+    git clone --recursive https://github.com/geonetwork/core-geonetwork.git \
+              geonetwork-$versionbranch
+    cd geonetwork-$versionbranch
+
+
+#. Create or move to the branch for the version
+
+
+.. code-block:: shell
+
+    # Create it if it does not exist yet
+    git checkout -b $versionbranch origin/develop
+
+    # Move into it if it exist
+    git checkout $versionbranch
+
+
+#. Update version number
+
+
+
+.. code-block:: shell
+
+    ./update-version.sh $currentversion $newversion
+
+
+
+#. Build the new release
+
+
+.. code-block:: shell
+
+    mvn clean install -DskipTests -Pwith-doc
+
+
+#. Create the installer
+
+
+.. code-block:: shell
+
+    cd installer
+    ant
+    cd ..
+
+
+#. Test the installer
+
+
+.. code-block:: shell
+
+    cd geonetwork-$version
+    java -jar geonetwork-$newversion/geonetwork-install-$newversion.jar
+
+
+
+# Generate list of changes
+
+
+.. code-block:: shell
+
+    cat <<EOF > docs/changes$newversion.txt
+    ================================================================================
+    ===
+    === GeoNetwork $version: List of changes
+    ===
+    ================================================================================
+    EOF
+    git log --pretty='format:- %s' origin/$previousversion... >> docs/changes$newversion.txt
+
+
+#. Commit the new version (in submodule first and then in the main module)
+
+
+.. code-block:: shell
+
+    cd geoserver
+    git add .
+    git commit -m "Update version to $newversion"
+    cd ..
+    git add .
+    git commit -m "Update version to $newversion"
+
+
+#. Tag the release
+
+
+.. code-block:: shell
+
+    git tag -a $version -m "Tag for $version release"
+    git push origin $version
+
+
+#. Set version number to SNAPSHOT
+
+
+.. code-block:: shell
+
+    ./update-version.sh $newversion $version-SNAPSHOT
+    git add .
+    git commit -m "Update version to $version-SNAPSHOT"
+    git push origin $versionbranch
+
+
+#. Publish in sourceforge
+
+
+.. code-block:: 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/cd GeoNetwork_unstable_development_versions/
+    mkdir 3.0.0
+    cd 3.0.0
+    put docs/changes$newversion.txt
+    put geonetwork*/*.jar
+    put web/target/geonetwork.war
+
+
+
+
+.. seealso::
+
+  Branches are not created for submodule. It may be relevant if the release plan to make major
+  changes in them.
+
+
+  .. code-block:: shell
+
+        for i in "${modules[@]}"
+        do
+              cd $i; git checkout -b $versionbranch origin/develop; cd ..
+        done
+
+
diff --git a/en/contributing/index.rst b/en/contributing/index.rst
@@ -1,4 +1,12 @@
 Contributing guide
 ##################
 
-The guide for people who want to contribute to GeoNetwork.
+The guide for people who want to contribute to GeoNetwork.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   writing-documentation.rst
+   making-a-pull-request.rst
+   doing-a-release.rst
diff --git a/en/contributing/making-a-pull-request.rst b/en/contributing/making-a-pull-request.rst
@@ -0,0 +1,4 @@
+.. _making-a-pull-request:
+
+Making a pull request
+#####################