"Fossies" - the Fresh Open Source Software Archive

Member "gdal-3.0.2/HOWTO-RELEASE" (28 Oct 2019, 10434 Bytes) of package /linux/privat/gdal-3.0.2.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "HOWTO-RELEASE": 2.3.3_vs_2.4.0.

    1 	Notes on Preparing a GDAL Source Release
    2 	========================================
    3 
    4 
    5 Prerequisites:
    6 
    7 1) Check that the release is ready to go as far as ABI (binary compatibility)
    8    is concerned. This can be checked by comparing the installed headers of the
    9    candidate release with the installed headers of the previous release
   10    (diff -ur $(OLD_INSTALL_DIR)/include $(NEW_INSTALL_DIR)/include). The API
   11    is defined as all functions and classes exported by the CPL_DLL keyword.
   12 
   13   - For major and minor releases, there must be no function signature change
   14     for the C API. Only new functions are allowed.
   15 
   16   - For major releases, the allowed changes in C++ API should (or must?) be
   17     such that user calling C++ code can still compile against new headers
   18     without modification (existing methods can become virtual, default
   19     arguments can be added, new methods or members can be added)
   20 
   21   - For minor releases (1.6.1 versus 1.6.0), the C++ ABI stability must be
   22     preserved : no method signature change, no addition of virtual methods, no
   23     new members. Only non-virtual methods can be added.
   24 
   25     It may also be helpful to check:
   26       https://abi-laboratory.pro/tracker/timeline/gdal/
   27 
   28 2) Delete existing fix_typos directory and run scripts/fix_typos.sh
   29 
   30 Process :
   31 
   32 1) a) Regenerate configure using autogen.sh and commit if changed.
   33    b) Regenerate swig generated files for python bindings and commit if changed.
   34 
   35    There is often a reference system on which this should be done (i.e. Frank's
   36    dev workstation) to avoid unnecessary churn from different autoconf or swig
   37    versions.
   38 
   39    c) "cd scripts; make completion" to regenerate scripts/gdal-bash-completion.sh
   40       if new command line switches have been added. scripts/completionFinder.py
   41       must also be edited before if new utilities/scripts are added/removed.
   42 
   43 2) Update the release date, and number information in gcore/gdal_version.h.in
   44    (*NOT* gdal_version.h which is a generated file)
   45    Note: the format of GDAL_RELEASE_DATE should be YYYYMMDD.
   46 
   47 3) Update the VERSION file.
   48 
   49 3.1) Update ./swig/python/setup.py version information.
   50      And the version of libgdal in ./swig/python/README.txt
   51 
   52 3.2) Update ./swig/include/perl/gdal_perl.i $VERSION and $GDAL_VERSION
   53 strings to current version. Update also $VERSION in
   54 ./swig/include/perl/ogr_perl.i to the same as the other $VERSION. Kick
   55 Perl module maintainer to make a CPAN release.
   56 
   57 3.3) For major releases update the VERSION macro in nmake.opt (for 1.6, 1.7etc)
   58 
   59 4) Update LIBGDAL_CURRENT/REVISION/AGE macros in GDALmake.opt.in.
   60    - For a release with no interface changes just bump REVISION.
   61    - Adding interfaces, bump CURRENT/AGE, set REVISION to 0.
   62    - Deleting interfaces / compatibility issues - bump CURRENT, others to zero.
   63 
   64 5) Prepare release overview in the NEWS file. For example, to get all changes
   65    from v2.2.0 to current HEAD (from gdal/ subdirectory)
   66      git log --reverse -v v2.2.0..HEAD .
   67 
   68   - commit new version to NEWS file.
   69 
   70 6) Update the GDAL http://trac.osgeo.org/gdal/wiki/DownloadSource topic to
   71    refer to the latest available source.
   72    Update http://trac.osgeo.org/gdal/wiki (Releases section)
   73    Update http://trac.osgeo.org/gdal/wiki/NewsAndStatus
   74 
   75 7) If this is a major release, prepare a branch.
   76 
   77    git checkout master
   78    git pull origin master
   79    git checkout -b release/2.3
   80    git push origin release/2.3
   81 
   82 8) Tag the release set in git:
   83 
   84    git checkout release/2.3
   85    git pull origin release/2.3
   86    git tag -a -m "Create tag v2.3.0" v2.3.0
   87    git push origin v2.3.0
   88 
   89 9) Create the source distributions using the mkgdaldist.sh script.  The
   90    argument should be the version number (i.e. 1.4.2). As our process involves
   91    doing betas or RCs, use the -rc option so that the filenames include this
   92    information (after promotion to official release, filename renaming will have
   93    to be done)
   94 
   95    % mkgdaldist.sh 2.3.0 -tag v2.3.0 -rc RC1
   96 
   97    For a beta version:
   98 
   99    % mkgdaldist.sh 2.3.0beta1 -tag v2.3.0beta1
  100 
  101 10) Create a snapshot of the documentation.
  102 
  103  i.e. On www.gdal.org:
  104  % cd /var/www/gdal
  105  % ./gdal-web-refresh.sh
  106  % zip -r ~/gdal230beta1doc.zip gdal-web --exclude "gdal-web/1.11/*" --exclude "gdal-web/daily/*"
  107 
  108 12) Publish the resulting files in download.osgeo.org/gdal/X.Y.Z (where X.Y.Z is the version number)
  109     and add a symlink from X.Y.Z to CURRENT (except for stable releases in a "old" branch).
  110 
  111   % ln -sf X.Y.Z CURRENT
  112 
  113 13) Announce release to :
  114     - major release: gdal-dev@lists.osgeo.org, gdal-announce@lists.osgeo.org, news_item@osgeo.org.
  115     - bugfix release: gdal-dev@lists.osgeo.org, gdal-announce@lists.osgeo.org
  116 
  117 Note: gdal-announce@ is moderated. Make sure that your email address is approved
  118 ('mod' tick disabled in https://lists.osgeo.org/mailman/admin/gdal-announce/members),
  119 or your message manually approved, with an administrator of the list.
  120 
  121 14) Update the freecode.com (previously freshmeat) entry for GDAL.
  122 
  123 15) Update the freegis.org entry for GDAL.
  124 
  125 16) Update doc/index.dox to advertize the new release and link to the release notes
  126 
  127 17) Create a News page in Trac for the release (like
  128 http://trac.osgeo.org/gdal/wiki/Release/1.7.0-News) and reference it from
  129 http://trac.osgeo.org/gdal/ (Releases) and
  130 http://trac.osgeo.org/gdal/wiki/NewsAndStatus .
  131 
  132 18) Add pointers to the source releases at:
  133 
  134   http://trac.osgeo.org/gdal/wiki/DownloadSource
  135 
  136 19) Update Trac to mark this release milestone as "Completed", and create
  137     a corresponding version.  Then create a new milestone for the next release.
  138 
  139 20) Upload the new Python bindings to Pypi (requires upload rights to
  140 the GDAL package by one of the current owners : HowardB/FrankW/EvenR)
  141 ( procedure taken from http://peterdowns.com/posts/first-time-with-pypi.html )
  142 
  143 a) Install twine https://pypi.org/project/twine/
  144 
  145 b) Create a $HOME/.pypirc file :
  146 
  147 [distutils] # this tells distutils what package indexes you can push to
  148 index-servers = pypi
  149                 pypitest
  150 
  151 [pypi] # authentication details for live PyPI
  152 repository: https://upload.pypi.org/legacy/
  153 username: yourlogin
  154 password: yourpassword
  155 
  156 [pypitest] # authentication details for test PyPI
  157 repository: https://test.pypi.org/legacy/
  158 username: yourlogin
  159 password: yourpassword
  160 
  161 c) cd swig/python
  162 
  163 d) python setup.py sdist
  164 
  165 e) For trial :
  166     twine upload dist/GDAL*.gz -r pypitest
  167 
  168 f) For real :
  169     twine upload dist/GDAL*.gz
  170 
  171 21) Build and bundle the java bindings.
  172 
  173 a) cd swig/java
  174 
  175 b) Make any updates to java.opt that might be required for the platform. For
  176    example osx and windows users will have to change JAVA_INCLUDE to contain
  177    include/darwin and include/win32 respectively.
  178 
  179 c) Build the bindings:
  180 
  181      make
  182 
  183 22) Build maven artifacts. NOTE: This step only works on Linux and OSX since it
  184     requires a shell script to build javadocs.
  185 
  186     A quick one-liner for this step is:
  187 
  188       ant maven_sign -Dgpg.key=... -Dgpg.pass=...
  189 
  190     This will build and sign the artifacts with a single command. Read on for
  191     more details.
  192 
  193 a)  Build the maven artifacts:
  194 
  195      ant maven
  196 
  197     Upon success maven artifacts should be located in the build/maven directory.
  198 
  199 b)  Sign maven artifacts with GPG. This step is required in order to deploy the
  200     maven artifacts to the central Maven repository. Before this step can
  201     proceed you must set up a signing key as described here:
  202 
  203       http://central.sonatype.org/pages/working-with-pgp-signatures.html
  204 
  205     Each developer can use their own signing key although it is usually best to
  206     avoid constantly using a different key for releases as users will need to
  207     import the public key in order to verify the artifacts.
  208 
  209     Here are a quick set of steps to generate a signing key key.
  210 
  211        gpg --gen-key
  212        gpg --list-keys (and note the key id)
  213        gpg --keyserver hkp://pool.sks-keyservers.net --send-keys <key id>
  214 
  215     See the above link for more details.
  216 
  217     Once a key is set up run the "maven_sign" ant target. The target takes two
  218     parameters specified as system properties:
  219 
  220     1. gpg.key - The identifier for the signing key
  221     2. gpg.pass - The passphrase for the signing key (optional)
  222 
  223       ant maven_sign -Dgpg.key=... -Dgpg.pass=...
  224 
  225     Upon success you should see maven artifacts along with generated signatures
  226     in the build/maven directory. You will also find a file named "bundle.jar"
  227     that contains all the maven artifacts with signatures. This file is what
  228     will be uploaded to maven central. See the next step.
  229 
  230 23) Deploy maven artifacts to Maven central.
  231 
  232     NOTE: Before you can deploy to maven central you must set up an account
  233     in Sonatype JIRA. That can be done here:
  234 
  235         https://issues.sonatype.org/secure/Signup!default.jspa
  236 
  237     Once you have an account set up you must be associated with the gdal
  238     project. Create a ticket here asking to be associated with the project:
  239 
  240         https://issues.sonatype.org/browse/OSSRH
  241 
  242     The entire deployment process is described in detail here:
  243 
  244        http://central.sonatype.org/pages/manual-staging-bundle-creation-and-deployment.html
  245        http://central.sonatype.org/pages/releasing-the-deployment.html
  246 
  247     The following steps summarize the process.
  248 
  249 a) Log into the Sonatype repository manager at https://oss.sonatype.org. Use the
  250    same credentials as your Sonatype JIRA account.
  251 
  252 b) Once log in select "Staging Upload" on the left hand side.
  253 
  254 c) Select "Artifact Bundle" under "Upload Mode" and then choose the "bundle.jar"
  255    created in the previous Step 22. Finally "Upload Bundle" to start the upload.
  256 
  257 d) When the upload has been completed you will be notified that a staging
  258    repository has been created. Note the name of the repository. It should look
  259    something like "orggdal-100x".
  260 
  261 e) From the left hand menu navigate to "Staging Repositories". In the search
  262    box look for the staging repository name you noted from the previous section.
  263    Or just search for "gdal". It should be obvious which repository is the
  264    current one.
  265 
  266 f) Select the staging repository. If all is well You should see the option to
  267    "Release" (Located as a button near the top of the page). If not it means
  268    there was an issue with the bundle. Consult the "Activity" tab at the bottom
  269    of the page to find out why.
  270 
  271 e) Click the "Release" button and that is it! The release should be available in
  272    Maven Central shortly. You can verify this by going to search.maven.org and
  273    searching for "gdal".
  274