docs: Prepare release notes for version 0.3.0

Change-Id: I25c1105546ac0c2108225cd578d88bbccec89cfc Refs: #2463, #2209, #2352
2015-02-02 14:09:55 -08:00
1 parent cf3a667634
commit 5946ed104b
@@ -0,0 +1 @@
+docs/RELEASE_NOTES.rst
@@ -101,7 +101,7 @@ The following lists steps for common platforms to install these prerequisites:

 -  On Fedora::

-       sudp yum install doxygen graphviz python-sphinx
+       sudo yum install doxygen graphviz python-sphinx
       sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics

 Build
@@ -243,3 +243,14 @@ running ``./waf configure``:

    CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
    ...
+
+Customize Compiler
+------------------
+
+To customize compiler, set ``CXX`` environment variable to point to compiler binary and, in
+some case, specify type of the compiler using ``--check-cxx-compiler``.  For example, when
+using clang compiler on Linux system, use the following:
+
+::
+
+    CXX=clang++ ./waf configure --check-cxx-compiler=clang++
@@ -3,6 +3,246 @@
 ndn-cxx Release Notes
 ---------------------

+ndn-cxx v0.3.0 (changes since version 0.2.0)
++++++++++++++++++++++++++++++++++++++++++++
+
+Release date: February 2, 2015
+
+New features:
+^^^^^^^^^^^^^
+
+- **Build**
+
+  + The code now requires C++11.  The minimum supported gcc version is 4.6, as earlier versions
+    do not have proper support for C++11 features.
+
+- **Base**
+
+  + Enable detailed version information when built from shallow clone or tarball
+    (:issue:`1915`)
+
+  + Make default transport configurable (:issue:`2189`)
+
+  + Add ability to do partial Name comparison (:issue:`2090`)
+
+- **Security**
+
+  + Add support for KeyDigest key locator (:issue:`1426`)
+
+  + Add a method to get KeyDigest from a PublicKey instance (:issue:`1964`)
+
+  + Add support for KeyChain to sign Interest using SHA256 digest (:issue:`2218`)
+
+  + Add ``ndnsec-dsk-gen`` tool to generate a pair of Data-Signing-Key (DSK) for the specified
+    identity  (:issue:`2246`)
+
+  + Pair-up PIB and TPM in KeyChain: PIB remembers the last used TPM type/location, which is
+    used during KeyChain construction (unless overriden) (:issue:`2242`)
+
+- **Wire encoding**
+
+  + Add support for application-defined meta information blocks (:issue:`2021`)
+
+  + Introduce new ``name::Component::is*`` methods to allow checking if the name component
+    follows the specific naming convention without relying on the exception handling
+    (:issue:`2088`)
+
+  + Add definition of producer-generated NACK (:issue:`2111`)
+
+  + Add ``std::hash<Name>`` specialization to support ``unordered_map`` container
+    (:issue:`2147`)
+
+  + Add support for ImplicitSha256DigestComponent (:issue:`1640`)
+
+  + Allow tagging Interest and Data packets with arbitrary information (:issue:`2336`)
+
+- **Management**
+
+  + Support NFD face query operation (:issue:`2085`)
+
+- **Miscellaneous tools**
+
+  + Add a new helper to calculate digests over dynamic inputs (:issue:`1934`)
+
+  + Add DNS resolver helper (:issue:`1918`)
+
+  + Import and re-license Ethernet and FaceUri classes from NFD codebase, add FaceUri
+    canonization support for ``udp``, ``tcp``, and ``ether`` schemas (:issue:`1994`)
+
+  + Add per-application in-memory storage with LRU, LFU, and FIFO replacement policies
+    (:issue:`1940`)
+
+  + Add ability to specialize system and steady clocks (e.g., for unit tests and simulation
+    purposes) (:issue:`2158`)
+
+  + Expose DummyClientFace as public API
+
+  + New IndentedStream helper class to simplify writing to streams with the specified indents
+    or prefixes (:issue:`2238`)
+
+  + New Signal class template as an enhanced version of the deprecated EventEmitter
+    (:issue:`2279`)
+
+  + New scheduler::ScopedEventId helper to automatically cancel scheduled events upon
+    destruction (:issue:`2442`)
+
+  + New NetworkMonitor helper to detect network state changes (:issue:`2443`)
+
+Updates and bug fixes:
+^^^^^^^^^^^^^^^^^^^^^^
+
+- **Base**
+
+  + Prevent flags being set for rib/unregister command (:issue:`1945`)
+
+  + Fix segfault caused by Face::unregisterPrefix when registeredPrefixId does not exist
+
+  + Add explicit internal KeyChain to Face class.  KeyChain previously existed in the Face as
+    part of NFD controller class.  (:issue:`2039`)
+
+  + Properly disable assertions in release builds (:issue:`2135`)
+
+  + Connect to Transport during construction of Face instance (:issue:`2318`)
+
+- **Wire encoding**
+
+  + Fix segfault when decoding empty Exclude element (:issue:`1970`)
+
+  + Provide EqualityComparable concept for Exclude element
+
+  + Correct Marker in Name::appendVersion() (:issue:`2086`)
+
+  + Ensure that wire-encoding errors are inherited from ``tlv::Error`` (:issue:`1983`)
+
+- **Management**
+
+  + Replace FaceFlags with individual fields in face management data structures (:issue:`1992`)
+
+  + ``ndn::nfd::Controller`` extended to allow generating ControlCommand for remote prefix
+    registration (:issue:`2039`)
+
+  + Change ``ForwarderStatus.NfdVersion`` to string (:issue:`2003`)
+
+- **Security**
+
+  + Fix ``ndnsec-cert-gen`` to correctly infer prefix before KEY component (:issue:`2052`)
+
+  + Help message corrections in ``ndnsec-cert-dump``, ``ndnsec-cert-gen``, and
+    ``ndnsec-key-gen`` (:issue:`2052`)
+
+  + Accept ``--sign-id`` and ``--cert-prefix`` in ``ndnsec-cert-revoke`` (:issue:`2058`)
+
+  + Changes output format of ``ndnsec-cert-revoke`` to base64 encoding (:issue:`2059`)
+
+  + Add a new (safer) option to ``ndnsec-cert-gen`` allowing inclusion of additional
+    information blocks into the certificate.  The new ``--signed-info`` parameter makes minimum
+    assumptions, treating text before first space as OID and the rest as the associated string
+    with this OID.
+
+  + Make Face optional in Validator class (:issue:`2124`)
+
+  + Display signature information when printing a certificate (:issue:`2196`)
+
+  + Handle certificate decoding error in validation process (:issue:`2212`)
+
+  + Fix segmentation fault in ``ndnsec-sign-req`` (:issue:`2211`)
+
+  + Allow verbose option in ``ndnsec-list`` (:issue:`2197`)
+
+  + Allow generation of DSK using ``ndnsec-key-gen`` (:issue:`2247`)
+
+  + Allow ``ndnsec-key-gen`` to generate ECDSA keys (:issue:`2248`)
+
+  + Fix memory leak in SecPublicInfoSqlite3 (:issue:`2253`)
+
+  + Properly report status of ``ndnsec-delete`` execution (:issue:`2275`)
+
+- **Miscellaneous tools**
+
+  + Fix incorrect tag map in ``tlvdump`` tool
+
+  + Change to default resolver behavior in util::dns::Resolver (:issue:`2415`)
+
+- **Documentation**
+
+  + Update of tutorials and installation instructions
+
+  + Rename manpage of ``client.conf`` to ``ndn-client.conf`` (:issue:`1967`)
+
+  + Updated and extended ndn-cxx code style:
+
+    - add rules for some C++11 constructs
+    - prefer ``BOOST_ASSERT`` and ``static_assert``
+
+  + Improve example applications (:issue:`1976`)
+
+- **Tests**
+
+  + Improve security unit test cases (:issue:`1683`)
+
+  + Embedding CI build and test running scripts into the repository
+
+  + Partial unit test coverage for Face class (previously covered only by integration tests)
+    (:issue:`1947`)
+
+  + Improve stability of unit tests by using UnitTestTime (wall clock independent time)
+    (:issue:`2152`)
+
+- **Build**
+
+  + Redesign the way default compiler flags are determined (:issue:`2209`)
+
+  + Support tools and examples with multiple translation units (:issue:`2344`)
+
+  + Disable installation of internal headers and headers of the disabled components
+    (:issue:`2266`, and :issue:`2269`)
+
+  + Enable conditional compilation based on presence of ``getpass()`` function
+
+- Other minor fixes and corrections
+
+Deprecated:
+^^^^^^^^^^^
+
+- ``ndn::ptr_lib`` and ``ndn::func_lib`` namespace aliases
+
+- The following ``nfd::Controller`` methods:
+
+  + ``Controller::start`` overloads, except the overload taking ``CommandOptions``
+  + ``Controller::Sign`` typedef
+  + ``Controller::getDefaultCommandTimeout``
+  + ``ControlCommand::getPrefix``
+  + ``ControlCommand::getRequestName(ControlParameters)``
+  + ``Controller::Controller(Face&)``
+
+- ``MetaInfo::TYPE_*`` constants
+
+- ``EventEmitter`` is deprecated in favor of ``Signal``
+
+Removed:
+^^^^^^^^
+
+- FaceFlags APIs (:issue:`1992`)
+
+- ``ControlCommand::makeCommandInterest`` (:issue:`2008`)
+
+- namespace ``ndn::Tlv`` (:issue:`2079`)
+
+- ``shared_ptr<io_service>`` constructor and getter in Face class
+
+- ``tlv::ConentType`` (typo in the name)
+
+- ``Selectors::Selectors(int, int, Exclude, int, bool)`` constructor
+
+- ``Interest::Interest(Name, int, int, Exclude, int, bool, int, time::milliseconds, uint32_t)``
+  constructor
+
+- ``signature-sha256.hpp`` file
+
+- unused ``encryption-manager.hpp`` file
+
+- unused ``openssl`` dependency
+
 ndn-cxx v0.2.0 (changes since version 0.1.0)
 ++++++++++++++++++++++++++++++++++++++++++++

@@ -26,8 +266,7 @@ New features:
      up application-specific ``OnInterest`` call dispatch using InterestFilters.

  + Add support for new `NDN naming conventions
-    <http://named-data.net/doc/tech-memos/naming-conventions.pdf>`_
-    (`Issue #1761 <http://redmine.named-data.net/issues/1761>`_)
+    <http://named-data.net/doc/tech-memos/naming-conventions.pdf>`_ (:issue:`1761`)

 - **Security**

@@ -49,35 +288,30 @@ New features:
  + :ndn-cxx:`Data::getFullName() <getFullName()>` method to get :ndn-cxx:`Data` packet
    name with implicit digest

-  + New :ndn-cxx:`Name::getSuccessor()` method to get `name successor
-    <http://redmine.named-data.net/issues/1677>`_
+  + New :ndn-cxx:`Name::getSuccessor()` method to get name successor (:issue:`1677`)

-  + New in-wire refreshing of Interest's nonce
-    (`Issue #1758 <http://redmine.named-data.net/issues/1758>`_)
+  + New in-wire refreshing of Interest's nonce (:issue:`1758`)

 - **Management**

  + Support for :ndn-cxx:`ChannelStatus`, :ndn-cxx:`StrategyChoice` datasets

-  + Defining new common Route Origins for NFD RIB management protocol
-    (`Issue #1719 <http://redmine.named-data.net/issues/1719>`_)
+  + Defining new common Route Origins for NFD RIB management protocol (:issue:`1719`)

-  + New RibEntry and Route data structures for RIB management protocol
-    (`Issue #1764 <http://redmine.named-data.net/issues/1764>`_)
+  + New RibEntry and Route data structures for RIB management protocol (:issue:`1764`)

-  + Add support for RIB flags for setInterestFilter and registerPrefix
-    (`Issue #1842 <http://redmine.named-data.net/issues/1842>`_)
+  + Add support for RIB flags for setInterestFilter and registerPrefix (:issue:`1842`)

 - **Miscellaneous tools**

  + Introduce :ndn-cxx:`Scheduler::cancelAllEvents` to cancel all previously scheduled events
-    (`Issue #1757 <http://redmine.named-data.net/issues/1757>`_)
+    (:issue:`1757`)

  + Introduce :ndn-cxx:`util::EventEmitter`, :ndn-cxx:`util::NotificationSubscriber`,
    :ndn-cxx:`util::NotificationStream`, and :ndn-cxx:`nfd::FaceMonitor` utility classes

  + Introduce :ndn-cxx:`util::SegmentFetcher` helper class to fetch multi-segmented data
-    (`Issue #1879 <http://redmine.named-data.net/issues/1879>`_)
+    (:issue:`1879`)

 - **Build**

@@ -88,18 +322,15 @@ Updates and bug fixes:

 - **Base**

-  + Serialization of socket write operations
-    (`Issue #1707 <http://redmine.named-data.net/issues/1707>`_)
+  + Serialization of socket write operations (:issue:`1707`)

-  + Enforcing limit on Interest and Data packet size in :ndn-cxx:`Face::expressInterest`
-    and :ndn-cxx:`Face::put` methods
-    (`Issue #1774 <http://redmine.named-data.net/issues/1774>`_)
+  + Enforcing limit on Interest and Data packet size in :ndn-cxx:`Face::expressInterest` and
+    :ndn-cxx:`Face::put` methods (:issue:`1774`)

  + Cleaning up transport state on communication failure, so Face can try to reconnect
    in the future.

-  + Fix bug with Face::removePendingInterest
-    (`Issue #1917 <http://redmine.named-data.net/issues/1917>`_)
+  + Fix bug with Face::removePendingInterest (:issue:`1917`)

 - **Wire encoding**

@@ -113,12 +344,11 @@ Updates and bug fixes:
    This way there is no extra memory allocation after :ndn-cxx:`Data` packet is signed.

  + Optimized implicit digest calculation in :ndn-cxx:`Interest::matchesData` method
-    (`Issue #1769 <http://redmine.named-data.net/issues/1769>`_)
+    (:issue:`1769`)

 - **Management**

-  + Add link-layer byte counts in FaceStatus data structure
-    (`Issue #1765 <http://redmine.named-data.net/issues/1765>`_)
+  + Add link-layer byte counts in FaceStatus data structure (:issue:`1765`)

 - **Security**

@@ -19,7 +19,7 @@ import re
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))

 # -- General configuration ------------------------------------------------

@@ -31,6 +31,7 @@ import re
 # ones.
 extensions = [
    'sphinx.ext.todo',
+    'redmine_issue',
 ]

 def addExtensionIfExists(extension):
@@ -272,4 +273,6 @@ if os.getenv('GOOGLE_ANALYTICS', None):
    googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
    googleanalytics_enabled = True

-exclude_patterns = ['RELEASE_NOTES.rst']
+# exclude_patterns = ['RELEASE_NOTES.rst']
+
+redmine_project_url = "http://redmine.named-data.net/"
@@ -1928,7 +1928,16 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

-PREDEFINED             =
+PREDEFINED             = DOXYGEN \
+                         NFD_LOG_INIT \
+                         BOOST_CONCEPT_ASSERT \
+                         PUBLIC_WITH_TESTS_ELSE_PROTECTED=protected \
+                         PUBLIC_WITH_TESTS_ELSE_PRIVATE=private \
+                         PROTECTED_WITH_TESTS_ELSE_PRIVATE=private \
+                         VIRTUAL_WITH_TESTS \
+                         DECL_OVERRIDE=override \
+                         NDN_CXX_KEYCHAIN_REGISTER_PIB \
+                         NDN_CXX_KEYCHAIN_REGISTER_TPM

 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -40,6 +40,8 @@ Documentation for ndn-cxx developers and contributors

 - :doc:`code-style`

+- :doc:`Release Notes <RELEASE_NOTES>`
+
 License
 -------

@@ -0,0 +1,70 @@
+# -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-
+# Based on http://doughellmann.com/2010/05/09/defining-custom-roles-in-sphinx.html
+
+"""Integration of Sphinx with Redmine.
+"""
+
+from docutils import nodes, utils
+from docutils.parsers.rst.roles import set_classes
+
+def redmine_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    """Link to a Redmine issue.
+
+    Returns 2 part tuple containing list of nodes to insert into the
+    document and a list of system messages.  Both are allowed to be
+    empty.
+
+    :param name: The role name used in the document.
+    :param rawtext: The entire markup snippet, with role.
+    :param text: The text marked with the role.
+    :param lineno: The line number where rawtext appears in the input.
+    :param inliner: The inliner instance that called us.
+    :param options: Directive options for customization.
+    :param content: The directive content for customization.
+    """
+    try:
+        issue_num = int(text)
+        if issue_num <= 0:
+            raise ValueError
+    except ValueError:
+        msg = inliner.reporter.error(
+            'Redmine issue number must be a number greater than or equal to 1; '
+            '"%s" is invalid.' % text, line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+    app = inliner.document.settings.env.app
+    node = make_link_node(rawtext, app, 'issues', str(issue_num), options)
+    return [node], []
+
+def make_link_node(rawtext, app, type, slug, options):
+    """Create a link to a Redmine resource.
+
+    :param rawtext: Text being replaced with link node.
+    :param app: Sphinx application context
+    :param type: Link type (issue, changeset, etc.)
+    :param slug: ID of the thing to link to
+    :param options: Options dictionary passed to role func.
+    """
+    #
+    try:
+        base = app.config.redmine_project_url
+        if not base:
+            raise AttributeError
+    except AttributeError, err:
+        raise ValueError('redmine_project_url configuration value is not set (%s)' % str(err))
+    #
+    slash = '/' if base[-1] != '/' else ''
+    ref = base + slash + type + '/' + slug + '/'
+    set_classes(options)
+    node = nodes.reference(rawtext, 'Issue #' + utils.unescape(slug), refuri=ref,
+                           **options)
+    return node
+
+def setup(app):
+    """Install the plugin.
+
+    :param app: Sphinx application context.
+    """
+    app.add_role('issue', redmine_role)
+    app.add_config_value('redmine_project_url', None, 'env')
+    return
@@ -1,6 +1,6 @@
 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
 /**
- * Copyright (c) 2013-2014 Regents of the University of California.
+ * Copyright (c) 2013-2015 Regents of the University of California.
 *
 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
 *
@@ -1,12 +1,12 @@
 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
 /**
- * Copyright (c) 2014,  Regents of the University of California,
- *                      Arizona Board of Regents,
- *                      Colorado State University,
- *                      University Pierre & Marie Curie, Sorbonne University,
- *                      Washington University in St. Louis,
- *                      Beijing Institute of Technology,
- *                      The University of Memphis
+ * Copyright (c) 2014-2015,  Regents of the University of California,
+ *                           Arizona Board of Regents,
+ *                           Colorado State University,
+ *                           University Pierre & Marie Curie, Sorbonne University,
+ *                           Washington University in St. Louis,
+ *                           Beijing Institute of Technology,
+ *                           The University of Memphis.
 *
 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
 *
@@ -1,6 +1,6 @@
 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
 /**
- * Copyright (c) 2013-2014 Regents of the University of California.
+ * Copyright (c) 2013-2015 Regents of the University of California.
 *
 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
 *
@@ -1,6 +1,6 @@
 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
 /**
- * Copyright (c) 2013-2014 Regents of the University of California.
+ * Copyright (c) 2013-2015 Regents of the University of California.
 *
 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
 *
@@ -3,7 +3,7 @@
 from waflib import Logs, Utils, Context
 import os

-VERSION = "0.2.0"
+VERSION = "0.3.0"
 APPNAME = "ndn-cxx"
 PACKAGE_BUGREPORT = "http://redmine.named-data.net/projects/ndn-cxx"
 PACKAGE_URL = "http://named-data.net/doc/ndn-cxx/"