# HG changeset patch # User Oleksandr Gavenko # Date 1322581744 -7200 # Node ID 989b5f7173f7ab226b3fdc8c2243e72457e0c9ea # Parent abbbaffa9c9fbeea173e63131b3609f060c489ed# Parent 140ed8e4da7f8c5abfdec656e5a7ac5235ac9b34 merged diff -r 140ed8e4da7f -r 989b5f7173f7 Makefile --- 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 >$@ ################################################################ diff -r 140ed8e4da7f -r 989b5f7173f7 cpp.rst --- a/cpp.rst Tue Nov 29 16:21:39 2011 +0200 +++ b/cpp.rst Tue Nov 29 17:49:04 2011 +0200 @@ -21,7 +21,9 @@ See: http://predef.sourceforge.net/ + ``predef`` project on Sourceforge http://en.wikipedia.org/wiki/C_preprocessor#Compiler-specific_predefined_macros + Compiler specific predefined macros http://msdn.microsoft.com/en-us/library/b0084kay.aspx Predefined Macros diff -r 140ed8e4da7f -r 989b5f7173f7 devel-proj-files.rst --- a/devel-proj-files.rst Tue Nov 29 16:21:39 2011 +0200 +++ b/devel-proj-files.rst Tue Nov 29 17:49:04 2011 +0200 @@ -87,16 +87,29 @@ ACKNOWLEDGEMENTS -Contributors files. -=================== +AUTHORS/THANKS files. +===================== -AUTHOR file. ------------- +AUTHORS/MAINTAINERS file. +------------------------- :: - authors - AUTHOR - AUTHORS + AUTHOR AUTHORS MAINTAINERS + + * Regular contributor list. + * List of project members with contact info (email, phone, home page, address, + etc). + +CONTRIBUTORS/THANKS/CREDITS file. +--------------------------------- +:: + + CONTRIBUTORS THANKS CREDITS ACKNOWLEDGEMENTS + + * Casual/non-regular contributor list. + +DEDICATION file. +---------------- README file. ============ @@ -281,30 +294,6 @@ CONVENTIONS file. ----------------- -Authors files. -============== - -AUTHORS/MAINTAINERS file. -------------------------- -:: - - AUTHOR AUTHORS MAINTAINERS - - * Usually regular contributors. - * List of project members with contact info (email/phone/home page/address/etc). - -CONTRIBUTORS/THANKS/CREDITS/ file. ----------------------------------- - - * Irregular contributor list. - * Usually casual/non-regular contributors. - -ACKNOWLEDGEMENTS file. ----------------------- - -DEDICATION file. ----------------- - Project changes files. ====================== diff -r 140ed8e4da7f -r 989b5f7173f7 devel-versioning.rst --- 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:: + + [`:'][`-'] + +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 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 is described below. The + portion of the version number is mandatory. + + The may contain only alphanumerics[1] and the characters + ``.`` ``+`` ``-`` ``:`` ``~`` (full stop, plus, hyphen, colon, tilde) and + should start with a digit. If there is no then hyphens + are not allowed; if there is no 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 + is. + + It is optional; if it isn't present then the + 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 at ``1`` each + time the 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 and . The absence of a + compares earlier than the presence of one (but + note that the is the least significant part of + the version number). + +The and 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