ReleaseGuide - Revision history

Guruofquality at 17:52, 18 June 2017

2017-06-18T17:52:20Z

← Older revision		Revision as of 18:52, 18 June 2017
Line 13:		Line 13:
	* The last digit is incremented for patch releases (0 - initial release, 1 - additional fixes, 2 - etc...)		* The last digit is incremented for patch releases (0 - initial release, 1 - additional fixes, 2 - etc...)

	* The project version number is set by modifying '''VERSION_MAJOR, MINOR~~, and~~ PATCH''' in the top level ~~CMakeLists~~.txt		* The project version number is set by modifying '''VERSION_MAJOR.MINOR.PATCH''' in the top level Changelog.txt

	===API version number===		===API version number===
Line 89:		Line 89:

	'''Note:''' If this is the first commit after a release, make sure to set a new version number 1) in the CMakeLists and 2) a new entry in the changelog. If this is the first API or ABI change after a release, also modify the relevant numbers in the CMakeLists/includes mentioned above.		'''Note:''' If this is the first commit after a release, make sure to set a new version number 1) in the CMakeLists and 2) a new entry in the changelog. If this is the first API or ABI change after a release, also modify the relevant numbers in the CMakeLists/includes mentioned above.

			'''Note2:''' And make sure that the images are available for the latest release. These major.minor numbers are used to format the URL so images can be versioned with the software: http://downloads.myriadrf.org/project/limesuite/

	==Debian packaging==		==Debian packaging==
Line 125:		Line 127:
	===Maintaining debian/===		===Maintaining debian/===

	The debian/ directory contains a few files that mirror the version numbers found in the ~~CMakeLists~~.txt. When making a new release the process is:		The debian/ directory contains a few files that mirror the version numbers found in the Changelog.txt. When making a new release the process is:

	* '''control''' - find and replace the version numbers for the current major release		* '''control''' - find and replace the version numbers for the current major release
Line 149:		Line 151:

	# Edit Changelog.txt, but the current date of the release and double check the version number		# Edit Changelog.txt, but the current date of the release and double check the version number
	~~# Make sure the MAJOR, MINOR, and PATCH in the CMakeLists.txt also match~~
	# Major release or ABI changes? update src/VersionInfo.h and debian/control and liblimesuite[version]-1.install files		# Major release or ABI changes? update src/VersionInfo.h and debian/control and liblimesuite[version]-1.install files
	# Make a new entry in debian/changelog to match		# Make a new entry in debian/changelog to match

Guruofquality: /* Making a release */

2017-06-18T04:27:08Z

Making a release

← Older revision		Revision as of 05:27, 18 June 2017
Line 132:		Line 132:

	==Making a release==		==Making a release==

			Making a release is a checklist of tasks to get all of the numbers right and to create a git tag:

			===Update numbers and dates===

			Is this a patch release?
			<pre>
			git checkout stable
			</pre>

			Is this a major/minor release?
			<pre>
			git checkout stable
			git pull origin master #master becomes the new stable
			</pre>

			# Edit Changelog.txt, but the current date of the release and double check the version number
			# Make sure the MAJOR, MINOR, and PATCH in the CMakeLists.txt also match
			# Major release or ABI changes? update src/VersionInfo.h and debian/control and liblimesuite[version]-1.install files
			# Make a new entry in debian/changelog to match
			# Finally commit the changes and push to stable

			===Make the git tag===

			After making the commit, make the tag to match the current version Follow this format:

			<pre>
			git tag -a v17.03.0 -m "Lime Suite v17.03.0"
			git push origin v17.03.0 #make it public
			</pre>

			===Update master===

			Always update the master branch to include the latest release information. No matter if this is a patch or major/minor release:

			<pre>
			git checkout master
			git pull . stable
			git push origin master #resolve any conflicts
			</pre>

Guruofquality: /* Debian packaging */

2017-06-18T03:36:54Z

Debian packaging

← Older revision		Revision as of 04:36, 18 June 2017
Line 91:		Line 91:

	==Debian packaging==		==Debian packaging==

			The project contains a debian/ directory for building debian source packages which can be used to upload to PPA among other things.

			===Building locally===

			Use the git build package tool to create a set of debs or to test the build:

			<pre>
			gbp buildpackage --git-ignore-new --git-ignore-branch --git-export=WC --git-upstream-tree=HEAD --git-export-dir=$HOME/build-area
			</pre>

			===Uploading to a PPA===

			Uploading a source package to the PPA involves

			# customizing the changelog with email and OS release,
			# running git build package to get a source package,
			# uploading the source package to the ppa with dput.

			I've created a helper script to automate the process. Feel free to pick it apart or change it.

			<pre>
			#this is an email registered with the PPA, pass it in with environment variables
			export DEBFULLNAME="YOUR NAME"
			export DEBEMAIL="YOUR-EMAIL@gmail.com"

			#run the PPA helper, specify the OS release (xenial)
			#The branch option will automatically used the latest release on that branch or
			#make a special version that is the latest release + number of commits since
			ppa_helper --source=/path/to/LimeSuite --branch=stable --series=xenial --suffix=myriadrf1 --upload=ppa:myriadrf/drivers
			</pre>

			===Maintaining debian/===

			The debian/ directory contains a few files that mirror the version numbers found in the CMakeLists.txt. When making a new release the process is:

			* '''control''' - find and replace the version numbers for the current major release
			* '''changelog''' - add a new entry for every major/minor and patch release
			* '''liblimesuite[version]-1.install''' - rename to match current library ABI

	==Making a release==		==Making a release==

Guruofquality: /* Git branching */

2017-06-16T03:30:21Z

Git branching

← Older revision		Revision as of 04:30, 16 June 2017
Line 73:		Line 73:
	* Push the commit(s) for the change and the Changelog to the stable branch.		* Push the commit(s) for the change and the Changelog to the stable branch.
	* Not its time to update the master branch. Merge stable into master and resolve any conflicts.		* Not its time to update the master branch. Merge stable into master and resolve any conflicts.

			'''Note:''' If this is the first commit after a release, make sure to increment the patch number 1) in the CMakeLists and 2) a new entry in the changelog.

	===The master branch===		===The master branch===

			The master branch contains new features and many times is subject to API and ABI changes. In general, the master branch should compile, though its possible that with new features come new bugs.

			'''Feature branches:''' When maintaining master, minor features and fixes for recent additions can go in at any time, but major features should be merged from a feature branch. Developing features on master could be disruptive to users. Its recommended to complete features on a dedicated "feature" branch and then to merge it into master when ready.

			'''Maintain the changelog:''' The master branch is a new major release in progress, and the changelog entry should contain brief descriptions. The entries should be pertinent to the next major release. For example: There's no need to mention fixes that only affect unreleased features. Pertinent entries might be:

			* API changes/breakages
			* major features/additions
			* removal/deprecations

			'''Note:''' If this is the first commit after a release, make sure to set a new version number 1) in the CMakeLists and 2) a new entry in the changelog. If this is the first API or ABI change after a release, also modify the relevant numbers in the CMakeLists/includes mentioned above.

	==Debian packaging==		==Debian packaging==

	==Making a release==		==Making a release==

Guruofquality: /* Git branching */

2017-06-16T02:56:00Z

Git branching

← Older revision		Revision as of 03:56, 16 June 2017
Line 66:		Line 66:

	The stable branch gives users a way to track the most recent release plus any new fixes. Patch releases will be tagged from the stable branch.		The stable branch gives users a way to track the most recent release plus any new fixes. Patch releases will be tagged from the stable branch.

			'''Here is the procedure for maintaining stable:'''

			* First a bug or typo is found. The fix should be applied to the stable branch (not master).
			* Edit the Changelog.txt with a brief description of the change. This makes it obvious what fixes have been addressed since the last release.
			* Push the commit(s) for the change and the Changelog to the stable branch.
			* Not its time to update the master branch. Merge stable into master and resolve any conflicts.

	===The master branch===		===The master branch===

Guruofquality: /* Git branching */

2017-05-25T07:51:40Z

Git branching

← Older revision		Revision as of 08:51, 25 May 2017
Line 57:		Line 57:

	==Git branching==		==Git branching==

			The LimeSuite repository has two important branches: stable and master.

			* The '''stable''' branch represents the latest release plus again additional fixes.
			* The '''master''' branch is is where new features and API/ABI changes occur.

			===The stable branch===

			The stable branch gives users a way to track the most recent release plus any new fixes. Patch releases will be tagged from the stable branch.

			===The master branch===

	==Debian packaging==		==Debian packaging==

	==Making a release==		==Making a release==

Guruofquality: /* Version numbers */

2017-05-25T06:30:24Z

Version numbers

← Older revision		Revision as of 07:30, 25 May 2017
Line 2:		Line 2:

	==Version numbers==		==Version numbers==

			The LimeSuite library has several similar version numbers to indicate project releases and other kinds of library compatibility. Mind them carefully. Here is a quick summary of these numbers and how they come into play. We will describe in more detail how to handle these numbers for making full and patch releases.

	===Project version number===		===Project version number===
Line 11:		Line 13:
	* The last digit is incremented for patch releases (0 - initial release, 1 - additional fixes, 2 - etc...)		* The last digit is incremented for patch releases (0 - initial release, 1 - additional fixes, 2 - etc...)

	* The version number is set by modifying '''VERSION_MAJOR, MINOR, and PATCH''' in the top level CMakeLists.txt		* The project version number is set by modifying '''VERSION_MAJOR, MINOR, and PATCH''' in the top level CMakeLists.txt

	===API version number===		===API version number===
Line 27:		Line 29:
	The usefulness of this this technique simply comes down to the specific circumstances. For example, a client application might have to maintain compatibility both for the current release and the yet-to-be-released stable branch that contains the API change.		The usefulness of this this technique simply comes down to the specific circumstances. For example, a client application might have to maintain compatibility both for the current release and the yet-to-be-released stable branch that contains the API change.

	* The API version is set ~~my modifying~~ '''LIME_SUITE_API_VERSION''' in '''src/VersionInfo.h'''		* The API version is set by editing '''LIME_SUITE_API_VERSION''' in '''src/VersionInfo.h'''

	===ABI version number===		===ABI version number===
Line 35:		Line 37:
	Although the ABI number is actually arbitrary, it should be used to represent the ABI of a version release, and changed when the ABI of the library actually changes.		Although the ABI number is actually arbitrary, it should be used to represent the ABI of a version release, and changed when the ABI of the library actually changes.
	In LimeSuite the ABI is set to '''major.minor-1''' by default. The only reason to change this, is if the ABI is broken for a patch release. This should be avoided in most cases.		In LimeSuite the ABI is set to '''major.minor-1''' by default. The only reason to change this, is if the ABI is broken for a patch release. This should be avoided in most cases.

			* The ABI version number can be modified by editing '''LIME_SUITE_SOVER''' in the top level CMakeLists.txt

	===Example unix library layout===		===Example unix library layout===

Guruofquality: /* Example unix library layout */

2017-05-25T06:25:20Z

Example unix library layout

← Older revision		Revision as of 07:25, 25 May 2017
Line 37:		Line 37:

	===Example unix library layout===		===Example unix library layout===

			Here is a demonstration for how these various version numbers come into play on a typical unix system

	<pre>		<pre>

Guruofquality: /* API version number */

2017-05-25T04:51:41Z

API version number

← Older revision		Revision as of 05:51, 25 May 2017
Line 17:		Line 17:
	The API version number is very similar to the project version number and it is primarily used for clients of the library to be able to detect API differences using preprocessor defines.		The API version number is very similar to the project version number and it is primarily used for clients of the library to be able to detect API differences using preprocessor defines.
	For example if the project version number is 17.03.*, the library API will be defined as '''#define LIME_SUITE_API_VERSION 0x20170300'''.		For example if the project version number is 17.03.*, the library API will be defined as '''#define LIME_SUITE_API_VERSION 0x20170300'''.
	A client application can use preprocessor macros and simple hex shifts to detect the ~~library~~ version.		A client application can use preprocessor macros and simple hex shifts to detect the API version.

	Typically, the API version will not change during a major.minor release cycle.		Typically, the API version will not change during a major.minor release cycle.
	However, consider that the 17.03.1 release had an important fix,		However, consider the following example: Suppose that the 17.03.1 release had an important fix,
	and by consequence modified how a particular API call operates under some conditions.		and by consequence modified how a particular API call operates under some conditions.
	To enable a client application to detect this change, we might modify the API accordingly '''#define LIME_SUITE_API_VERSION 0x20170301'''.		To enable a client application to detect this change, we might modify the API accordingly '''#define LIME_SUITE_API_VERSION 0x20170301'''.
	The last two digits don't have to match the patch number,		The last two digits don't have to match the patch number,
	they just need to be modified so that a client can detect that change in a meaningful way.		they just need to be modified so that a client can detect that change in a meaningful way.
			The usefulness of this this technique simply comes down to the specific circumstances. For example, a client application might have to maintain compatibility both for the current release and the yet-to-be-released stable branch that contains the API change.

	* The API version is set my modifying LIME_SUITE_API_VERSION in src/VersionInfo.h		* The API version is set my modifying '''LIME_SUITE_API_VERSION''' in '''src/VersionInfo.h'''

	===ABI version number===		===ABI version number===

Guruofquality: Created page with "The release guide is a helpful page intended to manage the creation of releases for the LimeSuite project, although its notes should be applicable to other projects. ==Versio..."

2017-05-25T04:40:55Z

Created page with "The release guide is a helpful page intended to manage the creation of releases for the LimeSuite project, although its notes should be applicable to other projects. ==Versio..."

New page

The release guide is a helpful page intended to manage the creation of releases for the LimeSuite project, although its notes should be applicable to other projects.

==Version numbers==

===Project version number===

The project has a 3 digit version number in the form of '''year.month.patch'''.

* The first digit is the current year as a two digit number (16, 17....)
* The second digit is the current month as a two digit number (01, 02, 03, 04..11, 12)
* The last digit is incremented for patch releases (0 - initial release, 1 - additional fixes, 2 - etc...)

* The version number is set by modifying '''VERSION_MAJOR, MINOR, and PATCH''' in the top level CMakeLists.txt

===API version number===

The API version number is very similar to the project version number and it is primarily used for clients of the library to be able to detect API differences using preprocessor defines.
For example if the project version number is 17.03.*, the library API will be defined as '''#define LIME_SUITE_API_VERSION 0x20170300'''.
A client application can use preprocessor macros and simple hex shifts to detect the library version.

Typically, the API version will not change during a major.minor release cycle.
However, consider that the 17.03.1 release had an important fix,
and by consequence modified how a particular API call operates under some conditions.
To enable a client application to detect this change, we might modify the API accordingly '''#define LIME_SUITE_API_VERSION 0x20170301'''.
The last two digits don't have to match the patch number,
they just need to be modified so that a client can detect that change in a meaningful way.

* The API version is set my modifying LIME_SUITE_API_VERSION in src/VersionInfo.h

===ABI version number===

The ABI version number represents the binary format of the library. The exact combination of functions, arguments, and classes form the ABI of the library. Typically, modifications of the headers of a library will cause ABI changes. If the ABI of the library is changed, its client applications must be recompiled or they will experience unknown failures like segmentation faults. On a unix system, the ABI is expressed as a suffix on the library. This allows multiple versions of the library to co-exist on one system.

Although the ABI number is actually arbitrary, it should be used to represent the ABI of a version release, and changed when the ABI of the library actually changes.
In LimeSuite the ABI is set to '''major.minor-1''' by default. The only reason to change this, is if the ABI is broken for a patch release. This should be avoided in most cases.

===Example unix library layout===

<pre>
ls -al /usr/lib/libLimeSuite*

libLimeSuite.so -> libLimeSuite.so.17.03-1
libLimeSuite.so.17.03-1 -> libLimeSuite.so.17.03.0
libLimeSuite.so.17.03.0
</pre>

* libLimeSuite.so is a symlink to the current library, its used for development purposes as a conveniently named file to link against
* libLimeSuite.so.17.03-1 is named after the ABI, other packaged applications look for this library by name. It symlinks to the latest installed version
* libLimeSuite.so.17.03.0 is the actual library file and is named after the currently installed version of the library package

==Git branching==

==Debian packaging==

==Making a release==