--- a/Makefile Tue Nov 29 16:21:39 2011 +0200
+++ b/Makefile Tue Nov 29 17:49:04 2011 +0200
@@ -22,11 +22,15 @@
################################################################
# Build tool definition/switches.
-RST2HTML = rst2html
+RST2HTML := rst2html
ifeq '$(host_os)' 'cygwin'
- RST2HTML = rst2html.py
+ RST2HTML := rst2html.py
endif
+RST_WARNING_FLAGS := --halt warning
+RST_FLAGS := --strip-comments
+RST_FLAGS += $(RST_WARNING_FLAGS)
+
################################################################
# Proj dirs/files.
@@ -35,7 +39,7 @@
HTML_DIR := tips-html
RST_HTML_FILES := $(patsubst %.rst,$(HTML_DIR)/%.html,$(RST_FILES))
-HTML_FILES := $(patsubst %.rst,$(HTML_DIR)/%.html,$(RST_FILES)) \
+HTML_FILES := $(RST_HTML_FILES) \
$(HTML_DIR)/index.html $(HTML_DIR)/frame.html $(HTML_DIR)/frame-index.html
TXT__FILES := $(addprefix $(HTML_DIR)/,$(TXT_FILES))
@@ -52,35 +56,35 @@
.PHONY: html
html: $(HTML_FILES) $(TXT__FILES)
-$(HTML_DIR)/%.html: %.rst rst.css | $(HTML_DIR)
- $(RST2HTML) --stylesheet=rst.css $*.rst $@
+$(HTML_DIR)/%.html: %.rst rst.css $(MAKEFILE_LIST) | $(HTML_DIR)
+ $(RST2HTML) $(RST_FLAGS) --stylesheet=rst.css $*.rst $@
-$(HTML_DIR)/frame-index.html: index.sh $(RST_HTML_FILES) | $(HTML_DIR)
+$(HTML_DIR)/frame-index.html: index.sh $(RST_HTML_FILES) $(MAKEFILE_LIST) | $(HTML_DIR)
./index.sh frame >$@
-$(HTML_DIR)/index.html: index.sh $(RST_HTML_FILES) | $(HTML_DIR)
+$(HTML_DIR)/index.html: index.sh $(RST_HTML_FILES) $(MAKEFILE_LIST) | $(HTML_DIR)
./index.sh html >$@
-$(HTML_DIR)/%.html: %.html | $(HTML_DIR)
+$(HTML_DIR)/%.html: %.html $(MAKEFILE_LIST) | $(HTML_DIR)
cp $< $@
-$(HTML_DIR)/%.txt: %.txt | $(HTML_DIR)
+$(HTML_DIR)/%.txt: %.txt $(MAKEFILE_LIST) | $(HTML_DIR)
cp $< $@
.PHONY: chm
chm: html $(CHM_FILES) $(HTML_DIR)/index-chm.html
cd $(HTML_DIR); for file in *.html; do sed -i '/<\?xml.*\?>/d' $$file; done
-$(HTML_DIR)/%.stp: %.stp | $(HTML_DIR)
+$(HTML_DIR)/%.stp: %.stp $(MAKEFILE_LIST) | $(HTML_DIR)
cp $< $@
-$(HTML_DIR)/chm.hhp: chm-hhp.sh | $(HTML_DIR)
+$(HTML_DIR)/chm.hhp: chm-hhp.sh $(MAKEFILE_LIST) | $(HTML_DIR)
./chm-hhp.sh >$@
-$(HTML_DIR)/chm.hhc: chm-hhc.sh | $(HTML_DIR)
+$(HTML_DIR)/chm.hhc: chm-hhc.sh $(MAKEFILE_LIST) | $(HTML_DIR)
./chm-hhc.sh >$@
-$(HTML_DIR)/index-chm.html: index.sh | $(HTML_DIR)
+$(HTML_DIR)/index-chm.html: index.sh $(MAKEFILE_LIST) | $(HTML_DIR)
./index.sh html >$@
################################################################
--- a/devel-versioning.rst Tue Nov 29 16:21:39 2011 +0200
+++ b/devel-versioning.rst Tue Nov 29 17:49:04 2011 +0200
@@ -30,11 +30,12 @@
There discussed:
* Is it essential to update major version if significant change made for
- licence? Answer: NO!
+ licence? Answer: **NO**!
GPLv3 is a big deal spread out over the whole GNU project, but not a big deal
for GDB in particular.
- * Is it right follow date version schema regardless major changes? Answer: NO!
+ * Is it right follow date version schema regardless major changes? Answer:
+ **NO**!
Many OS distribution encode year in versions but versions does not present
featureset but package set instead.
@@ -71,6 +72,25 @@
Prefixing version with a "v" seems to be less common.
+Version in package/release name.
+================================
+::
+
+ PACKAGE-MAJ.MIN.FIX.tar.gz (Common style)
+ PACKAGE-MAJ.MIN.FIX.zip
+ PACKAGE-MAJ.MIN.FIX-DISTROFIX.tar.gz (Cygwin style)
+ PACKAGE_EPOCH:MAJ.MIN.FIX-DISTROFIX_ARCH.deb (Debian style)
+
+From "Debian Policy Manual"::
+
+ Package names must consist only of lower case letters (`a-z'), digits
+ (`0-9'), plus (`+') and minus (`-') signs, and periods (`.'). They
+ must be at least two characters long and must start with an
+ alphanumeric character.
+
+If you look carefully there are no any ``_`` (underscore) chars!! Also ``-`` is
+portable char in file name accoding to POSIX.
+
Versioning for libraries/modules/components.
============================================
@@ -115,17 +135,36 @@
* rc (release candidate) are believed to meet all of the criteria for release
and can be installed on test instances of production systems.
+Compatibility formula.
+----------------------
+
+Assume that app linked with new version of lib. Thus::
+
+ is_compatible_with_old(old, new) {
+ if (old.major != new.major) return 0;
+ if (old.minor > new.minor) return 0;
+ return 1;
+ }
+
+Assume that app linked with old version of lib. Thus::
+
+ is_compatible_with_new(old, new) {
+ if (old.major != new.major) return 0;
+ return 1;
+ }
+
Versioning for products.
========================
Versioning for products differ from versioning for libraries.
-Product is a set of conponents fixed to some versions. Components can be
+Product is a set of conponents that stalled to some versions. Components can be
switches as written for library versioning:
- * Any fix release interchanged.
- * Any minor release interchanged starting from some minor.
- * Major release does not interchanged at all.
+ * Any fix releases interchanged, greater version mean less bug count.
+ * Any minor release interchanged with next minor releases.
+ * Major release does not interchanged at all, switching from old to new require
+ upgrade.
Product update vs upgrade.
--------------------------
@@ -135,14 +174,14 @@
* Replacing product executable files, resources files.
* Config files and user data stay unchanged.
-Product update involve:
+Product upgrade involve:
* Replacing product executable files, resources files.
* Config files and used data require modification and performed by upgrade
- scripts or manually by user.
+ scripts or manually by user (if this is ever possible).
-Release build version data.
-===========================
+Build data.
+===========
* Build number.
* Build date.
@@ -151,7 +190,7 @@
* Overnight build (Y/N).
* QA tested (Y/N).
* QA test results (Pass/Fail).
- * Location of full logs.
+ * Location of full build logs.
Stop your VCS hook to update version!
=====================================
@@ -161,10 +200,11 @@
Why do not do this on success build:
* You can have several build machine which may concurrently update version.
- * There not exist tools for easy querying for status of build (as ok/fail,
- build configuration, date, coverage, lint checks, etc).
+ * There does not exist tools for easy querying for status of build by its
+ number (as ok/fail, build configuration, date, coverage, lint checks status,
+ etc).
* Some part of development team may not have permission for bumping version and
- after build they must revert some automatically updated files.
+ they must revert some automatically updated files after build.
Why do not do this from pre-/post-commit hooks:
@@ -186,7 +226,100 @@
Debian version ordering formula.
--------------------------------
-TODO
+The version number of a package. The format is::
+
+ [<epoch>`:']<upstream_version>[`-'<debian_revision>]
+
+The three components here are:
+
+``epoch``
+ This is a single (generally small) unsigned integer. It may be
+ omitted, in which case zero is assumed. If it is omitted then
+ the <upstream_version> may not contain any colons.
+
+ It is provided to allow mistakes in the version numbers of older
+ versions of a package, and also a package's previous version
+ numbering schemes, to be left behind.
+
+``upstream_version``
+ This is the main part of the version number. It is usually the
+ version number of the original ("upstream") package from which
+ the ``.deb`` file has been made, if this is applicable. Usually
+ this will be in the same format as that specified by the upstream
+ author(s); however, it may need to be reformatted to fit into the
+ package management system's format and comparison scheme.
+
+ The comparison behavior of the package management system with
+ respect to the <upstream_version> is described below. The
+ <upstream_version> portion of the version number is mandatory.
+
+ The <upstream_version> may contain only alphanumerics[1] and the characters
+ ``.`` ``+`` ``-`` ``:`` ``~`` (full stop, plus, hyphen, colon, tilde) and
+ should start with a digit. If there is no <debian_revision> then hyphens
+ are not allowed; if there is no <epoch> then colons are not allowed.
+
+``debian_revision``
+ This part of the version number specifies the version of the
+ Debian package based on the upstream version. It may contain
+ only alphanumerics and the characters ``+`` ``.`` ``~`` (plus, full
+ stop, tilde) and is compared in the same way as the
+ <upstream_version> is.
+
+ It is optional; if it isn't present then the <upstream_version>
+ may not contain a hyphen. This format represents the case where
+ a piece of software was written specifically to be turned into a
+ Debian package, and so there is only one "debianisation" of it
+ and therefore no revision indication is required.
+
+ It is conventional to restart the <debian_revision> at ``1`` each
+ time the <upstream_version> is increased.
+
+ The package management system will break the version number apart
+ at the last hyphen in the string (if there is one) to determine
+ the <upstream_version> and <debian_revision>. The absence of a
+ <debian_revision> compares earlier than the presence of one (but
+ note that the <debian_revision> is the least significant part of
+ the version number).
+
+The <upstream_version> and <debian_revision> parts are compared by the
+package management system using the same algorithm:
+
+The strings are compared from left to right.
+
+First the initial part of each string consisting entirely of non-digit
+characters is determined. These two parts (one of which may be empty)
+are compared lexically. If a difference is found it is returned. The
+lexical comparison is a comparison of ASCII values modified so that
+all the letters sort earlier than all the non-letters and so that a
+tilde sorts before anything, even the end of a part. For example, the
+following parts are in sorted order from earliest to latest: ``~~``,
+``~~a``, ``~``, the empty part, ``a``.[2]
+
+Then the initial part of the remainder of each string which consists
+entirely of digit characters is determined. The numerical values of
+these two parts are compared, and any difference found is returned as
+the result of the comparison. For these purposes an empty string
+(which can only occur at the end of one or both version strings being
+compared) counts as zero.
+
+These two steps (comparing and removing initial non-digit strings and
+initial digit strings) are repeated until a difference is found or
+both strings are exhausted.
+
+Note that the purpose of epochs is to allow us to leave behind
+mistakes in version numbering, and to cope with situations where the
+version numbering scheme changes. It is _not_ intended to cope with
+version numbers containing strings of letters which the package
+management system cannot interpret (such as ``ALPHA`` or ``pre-``), or
+with silly orderings (the author of this manual has heard of a package
+whose versions went ``1.1``, ``1.2``, ``1.3``, ``1``, ``2.1``, ``2.2``,
+``2`` and so forth).
+
+[1] Alphanumerics are ``A-Za-z0-9`` only.
+
+[2] One common use of ``~`` is for upstream pre-releases. For example,
+ ``1.0~beta1~svn1245`` sorts earlier than ``1.0~beta1``, which sorts
+ earlier than ``1.0``.
Semver version ordering formula.
--------------------------------
@@ -213,8 +346,28 @@
Forms of compatibility.
=======================
-Runtime of binary compatibility mean that binary can be swaped with another
-version without breaking.
+Backward/forward compatibility.
+-------------------------------
+
+Backward compatibility for library, file format, protocol means that new version
+of program can work with old library, file format, protocol.
+
+Forward compatibility for library, file format, protocol means that old version
+of program can work with new library, file format, protocol but without using
+any benefits from new versions and more essentially without posibility damage
+any user data.
+
+Example of backward compatibility: adding to graphic library new image format
+for reading/saving.
+
+Example of forward compatibility: old browser ignore any new (unknown) HTML
+tags.
+
+Source/binary compatibility.
+----------------------------
+
+Runtime or binary compatibility mean that binary can be swaped with another
+version without breaking normal program work.
Compile time or source compatibility mean that supplied header/interfaces allow
successful compiling/linking.
@@ -223,38 +376,93 @@
* Change type of argument in method to more generic take source compatibility
but break binary compatibility.
- * Adding new mothod to abstract class take binary compatibility but break
+ * Adding new method to abstract class take binary compatibility but break
compilation (unimplement method error).
-File format compatibility.
+Format or protocol compatibility.
+---------------------------------
-Protocol compatibility.
+File format or protocol backward compatibility mean that new program can use old
+format or protocol.
+
+In order to do that file format or protocol MUST store or provide some
+versioning information. Usually this done by:
-Compatibility formula.
-======================
+ * Separate versioning field in data.
+ * New prefix or name in data.
+ * List of feature requirements, supported algorighm, etc.
+
+It is essential to make code that detect unknown or possibly new format or
+protocol and stop working with them to avoid user data corruption.
-Assume that app linked with new version of lib. Thus::
+It is essential to make file format or protocol extensible. This can be achieved
+by:
+
+ * Reserving some possible names/prefixes for future use.
+ * Generalising file format or protocol to envelop more cases.
+
+Extracting version from VCS.
+============================
- is_compatible_with_old(old, new) {
- if (old.major != new.major) return 0;
- if (old.minor > new.minor) return 0;
- return 1;
- }
+Including version in sources.
+=============================
+
+Don't use any ``$REVISION`` like keywords (usual practice in CVS, SVN)!
+
+Use sed, awk, M4 or any other preprocessor for non-compiled or non-preprocessed
+files (like .lisp, .py, .java files)::
+
+ $ cat my-version.el.in
+ (defvar my-major-version @VMAJOR@
+ "Major version.")
+ (defvar my-major-version @VMAJOR@
+ "Major version.")
+ (provide 'my-version)
-Assume that app linked with old version of lib. Thus::
+ $ cat Makefile
+ %: %.in
+ sed -e 's|@VMAJOR@|$(VMAJOR)|' -e 's|@VMINOR@|$(VMINOR)|' <$< >$@
+
+Pass version component to preprocessed file (like .c, .cxx files) through
+preprocessor::
- is_compatible_with_new(old, new) {
- if (old.major != new.major) return 0;
- return 1;
- }
+ $ cat my-version.c
+ int get_major_version() { return VMAJOR; }
+ int get_minor_version() { return VMINOR; }
+
+ $ cat Makefile
+ %.o: %.c
+ $(CC) -DVMAJOR=$(VMAJOR) -DVMINOR=$(VMINOR) -o $@ $<
Reference.
==========
- https://developer.mozilla.org/en/toolkit_version_format
- Toolkit version format
- http://apr.apache.org/versioning.html
- APR's Version Numbering
http://semver.org/
Semantic Versioning
+ http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version
+ Debian
+ http://www.openbsd.org/faq/ports/specialtopics.html
+ OpenBSD
+ http://java.sun.com/j2se/versioning_naming.html
+ Oracle
+ http://www.intel.com/support/graphics/sb/CS-020667.htm
+ Intel
+ http://wiki.eclipse.org/index.php/Version_Numbering
+ Eclipse
+ http://apr.apache.org/versioning.html
+ Apache
+ http://www106.pair.com/rhp/parallel.html
+ Conflict resolution
+ http://www.rpm.org/wiki/PackagerDocs/Dependencies
+ RH
+ http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html
+ RH
+ http://fedoraproject.org/wiki/Packaging/NamingGuidelines
+ RH
+ http://wikis.sun.com/display/IpsBestPractices/Packaging+Best+Practices+-+Versioning
+ Oracle
+ http://docs.codehaus.org/display/MAVEN/Dependency+Mediation+and+Conflict+Resolution
+ Maven
+ http://docs.codehaus.org/display/MAVEN/Versioning
+ Maven