What is the best method to determine the version number I should use for a software or component? Is there a general rule to set version numbers?
I'm pretty sure it is a basic question but I didn't find anything useful after searching a while.
Microsoft have a convention of:
[major].[minor].[revision].[build]
Or follow Jeff's versioning system.
I've been doing this as an interim until I find a better solution. I don't build many large applications, mostly reports and smaller macros, but it's still important for me to keep track of changes and versions.
[Current year].[Current month].[Current day]
FileName 9.7.17.rpt for example.
It works for me and my boss, and it gives a value which you can compare to today's date to see how old the file is. I also keep a changelog.txt file in the same folder as the most current version and it keeps track of all the changes from the previous versions. I also keep track of all versions in a version control page on each projects tab in OneNote.
Thanks for the answer. I'll also throw in how I store the projects for giggles.
Every project gets its own folder. Inside that folder I'll have 4 main items that help me keep track of what's going on in the project.
An old versions folder
A folder for any reference material I might need for the project
The actual project file
And the changelog
That tree will look something like this.
Project X
Old versions
X Report 9.4.12.rpt
X Report 9.5.3.rpt
X Report 9.7.20.rpt
Reference
SQL calls.txt
Client list.txt
Procedures.doc
X Report 9.7.29.rpt
X Report changelog.txt
This way of keeping track of my work really cuts down on the amount of time that I need to spend documenting anything and organizes it in a standard way so if my boss needs to grab something I've worked on, even he knows exactly what everything means and where it is.
For storing multiple projects in my network folder I have these folders.
Inbox
Projects
#Archived Projects
Current Project 1
Current Project 2
Current Project 3
Reference
Inbox is where I toss random things to process later, or a folder where my boss can throw something I'm going to need for a later project. The Projects folder contains all the projects I'm currently working on, and then when I'm done or they no longer become a current priority, they get tossed in #Archived Projects. Reference is a folder for general job reference material, like policies and procedures, phone lists, org charts, fire escape plans. I may never use them, but it's comforting to have a place to put that kind of stuff as opposed to digging through old email.
This is a very common question. Are you sure you searched around? Wikipedia has a good article on software versioning.
Or, you can follow Ubuntu's convention of using year and month.
For example, release on April 2009 would be:
v9.04
Do it like Donald Knuth does with TeX---its version converges to π with each release and will in fact become π when he dies.
Since version 3, TeX has used an
idiosyncratic version numbering
system, where updates have been
indicated by adding an extra digit at
the end of the decimal, so that the
version number asymptotically
approaches π. This is a reflection of
the fact that TeX is now very stable,
and only minor updates are
anticipated. The current version of
TeX is 3.1415926; it was last updated
in March 2008.
from Wikipedia
A common scheme seems to be to use [major].[minor].[revision]. Where the major version number increments on large/major feature changes or rewrites (or stays 0 as long as you didn't reach a stable version, although many open source projects never get past 0 here), minor version number increases on minor changes, such as a collection of bugfixes, an added small feature and the like. revision increments with each build and reflects the smallest granularity of tracking your exact version. Things like small fixes, etc. get rolled into this, usually.
Usually the first number are major changes/major releases, the second number are used when minor features and bug fixes are added, and the third number is used for minor bug fixes and revision numbers.
Ex. 1.0.0
Depends on a lot of things.
If you are doing .Net work, you can have the system keep track of version numbers for your .dlls and .exe files automatically.
We frequently use the subversion revision as part of our version number. We use a system like:
major.minor.svn-version
We increment the major/minor manually based on internal decisions, and have the svn-version propagate to distinguish builds.
The most important thing is that version numbers make sense to your users.
Related
Title says it all. What, if any, Is the difference between a software 'release' and a 'version'?
Do these two definitions overlap? Is it the case that all releases, and release candidates are versions, but not all versions are releases?
Here's a simplistic explanation:
Build − executable or a library created by compiling source code.
Version − a software build. New version is a different build.
Release − (public release) a version intended for use by general population.
Build #465832567 is just the number of times the main developer compiled the program (or library). Sensible developers only release builds with meaningful and tested changes.
Version 2.1.5 means it's the second edition with at least 1 major difference from its 2.0.~ predecessors and 5 minor feature updates or bug fixes.
"Public release" usually means it's a version for normal users who are not involved in testing or development of the software.
Different release types example:
Firefox − browser version for simple users
Aurora − so called "alpha" version, which includes latest additions, some untested
Nightly − "beta" version for developers and enthusiasts who don't fear bugs and crashes
I am not sure if there is a very concrete on these two terms, and the definition seems also differs base on context.
Normally Release is more about the "action" to distribute the software to interested candidates, while "version" is an identifier of certain snapshot of the software (mostly a meaningful snapshot).
Therefore, in most case, as we need to identify certain release of the application, we will have a version assigned. (There are always exceptions anyway...)
Definition of version:
a particular form of something differing in certain respects from an earlier form or other forms of the same type of thing.
Think of it this way.
When you edit the code, depending apon what you consider a change (saving, publishing, or just editing), your code version changes (depending on how large of a difference you consider a version- also note that versioning systems can be whatever you decide). You might have a version of code where there is a bug, then you patch it, and you have another version. What you call your versions can be whatever you want (versioning system).
A release is commonly considered a version that is pretty stable, complete, tested and most likely having few known bugs and then made public, although more technically its ANY version made public. However, when you see the word release I feel it is safe to assume it is the first provided you cant figure it out by context.
This is my second post so I hope it was helpful!
A release describes more the process of publishing a software than a concrete material thing. Whereas a version is a concrete and specific software package. Because you won’t publish all software versions you build, only the software versions that you publish or deliver are called software releases. A build is the process of compiling and packaging of a software. Because you can build one and the same code more than once at different machines and with different compilers in different environments a build is the outcome of compile and packaging code and software parts.
Imagine you plan, design, develop, build and test a software. All this steps bring you towards a software release. Because you don’t exactly know how much fixes and versions your team has to build and your quality assurance rejects you must define an objective for you team and your customers. So a release is an objective your team develops towards.
So let’s say you plan your first release in November. The objective of your team is to create a “Halloween Release”. Towards this “Halloween Release” you think it’s clever to present it to our QA before delivering the first version to key users or customers. So the intermediate objective of your team is to create a QA-Release or Alpha-Release. After the 1001st build you present a first running version for example 1.0-alpha-build-1001 to your QA. But your QA rejects this version and the following version as well. So you further fix, improve and build to get a Beta Release that your QA accepts for presentation to key users. Then some builds after, your QA confirms so you can present 1.0-beta-build-4711 to your key users; your first Beta-Release. After some improvements you publish your “Halloween Release” at November with version 1.0 as final software version to your customers. But unfortunately some customers complain about minor issues and some users do complain about missing features. In consequence you decide to fix the issues on the one hand and to integrate new features on the other hand. So your team has two goals and objectives, first to fix and to work towards a “Bugfix release” and second to work for a “Christmas Release” with the new features.
So you fix and build a “Bugfix release”, maybe resulting in a version 1.1. In parallel your team creates new features, integrates, tests and builds a “Christmas release”, resulting in a version 2.0 you deliver at Christmas to your customers.
So in one sentence: A release is a challenge towards a version, you deliver to a particular addresse:
QA-Releases for your QA to examine your software.
Beta-Releases for your key users to introduce new features.
Customer releases for customers to satisfy customers and make money.
Seasonal releases and other releases for funny as serious objectives as well.
Does anyone know of an MSSCCAPI provider for Mercurial? I'd like to try out Kiln/Mercurial with PowerBuilder, but the PowerBuilder IDE only recognizes MSSCCAPI providers (which is not the same as MS SCC Package API) and the only one I can find is the original version of HgSccPackage.
I've contacted the developer and he has stated that he will not switch back from the Package to the regular API so that option leaves me with no upgrade path. This question was asked in July of 2010 with only the response that I have already mentioned. I'm hoping there's been something new since then. Thanks!
I don't have enough rep to post this as a comment to the question.
Maybe your PowerBuilder source control methodology is holding you back. Do you control the PB objects inside of the PBLs? Or do you control *.sr? (PB Export) files, maybe using PowerGen to synchronize them into the PBLs?
At work, a set of PBLs is published to programmers by the Build Manager at every build. This avoids having to pay one PowerGen license per programmer for them to sync up (which can take 5-40 minutes depending on the number of changes and the app size). You need just one license for the build server.
One caveat is that programmers need to understand the flow correctly so not to lose code or cause regressions, but a good inspection of the TortoiseHg diff window should allow to catch most problems before committing.
I've got lots of source code files written in various languages, but none of them have a standard comment at the top (sometimes even across the same project). Some of them don't have any header comment at all :-)
I've been thinking about creating a standard template that I can use at the top of my source files, and was wondering what fields I should include.
I know I want to include my name and a short description of what the file contains/does. Should I also include the date created? The date last modified? The programmer who last modified the file? What other fields have you found to be useful?
Any tips and comments welcome.
Thanks,
Cameron
This seems to be a dying practice.
Some people here on StackOverflow are against code comments altogether (reasoning that code should be written to be self explanatory) While I wouldn't go that far, some of the points of the anti-comment crowd make sense, such as the fact that comments tend to be out of date.
Header blocks of comments suffer from these symptoms even more so. Every organization I've been with that has had these header blocks, they are out of date. They have a author name of some guy who doesnt even work there any more, a description that does not match the code at all (assuming it ever did) and a last modified date, that once compared with version control history, seems to have missed its last dozen updates.
In my personal opinion, keep comments close to the code. If you want to know purpose of, and/or history of, a code file, use your version control system.
Date created, date modified and author who last changed the file should be stored in your source control software.
I usually put:
The main purpose of the file and things within the file.
The project/module the file belongs to.
The license associated with the file (and a LICENSE file in the project root).
Who is responsible for the file (either the team, person, or both)
Back in 2002, when I was straight out of college and jobs were few and far between after the dot-com bust, I joined a service company which used to create software customized for their clients in Java. I had to sit in the office of a client (which was a ramshackle room in an electric sub-station rigged with an AC to keep the servers running), sharing chairs/PCs with other guys in the team. The other engineers (if I can call them engineers ;) in the group used to make changes ad-hoc to the source code, compile the files and put them into production.
No way to figure out who made what change.
No way to figure out why any change was made.
No way to go to previous version of code, unless the engineer "remembered" what he modified.
Backup: Copy over files from the production server, which were replaced with new files.
Location of backup: Home directory of engineer copying over files to production server.
Reports of production servers going down due to botched attempts of copying over files to the server (missed a file to be copied over, backups getting lost or wrong files being copied over or not all files being copied over) were met with shrugs (oh no, is it down? let's see what happened; hey who changed what recently...? ummm...).
During those days, after spending several frustrating days trying to figure out the whos and whys behind the code, I had devised a system for comments in a list in the header of the source file which detailed the following:
Date of change made
Who made the change
Why was the change made
Two months later when the list threatened to challenge the size of the source code in the file, the manager had the bright idea of getting a source version control system.
I have never needed to put any comments in headers of source files (except for copyright notices) in any company I worked since. In my current company, everything else is mostly self-evident by looking at the code, or going to the bug reporting system which is integrated with the source version control system.
What fields do you need? If you have to ask whether to put some info there, you don't really need that info. Unless you are forced, by some bureaucratic incompetence of your employer, I don't see why you should go looking for more info than you already feel should be there.\
In most organizations, all source files have to begin with a legal blurb. If you're really lucky, it's just a one-liner, but in most cases it's a really long block of legalese. As a result, few people ever read these. Our eye just travels to the first program element and then goes up to its documentation.
So if you want to write anything, write it in association with the topmost program element, not the file.
Any other bookkeeping information should generally be part of your version control, not maintained (poorly) in the file itself.
In addition to the comment above stating license, the project that it belongs to, etc I also tend to put the "weird" requirements at the top as well (such as "built with version X of library Y") so you, or the person who picks it up after you won't change something that the program relies on without realizing it (or, if they do, they will at least know what to change back)
A lot depends on whether you're using an auto-documentation generation tool or not.
While I agree with many of the comments, if you're using JavaDoc or some other documentation generating tool that depends on comments, you'll obviously need to include the things it wants to see.
You did not mention that you are using a version control system and your comment in Neil N's answer confirms this for your older code. While using version control is the best way to go I also have experienced many situations where the cost of doing so for older code would not be paid for by the project's sponsor. If you do not have a centralized change history for the project then the change history can be put in the modules. It is good that you are using a version control system for your new code.
Your company name
All rights reserved (c) year - or reference to appropriate license
Project or library this file is for
Module it belongs to
Description of what it contains
History
-------
01/08/2010 - Programmer - version
Initial creation.
01/09/2010 - Programmer - version
Change description.
01/10/2010 - Programmer - version
Change description.
Those useful fields that you mentioned are good ones. Who modified the file and when.
Your version control software should allow for the embedding of keywords within comments. For example, in CVS, the $Id$ will resolve to the file, date/time modified, and user that modified the file. It will automatically be kept up to date with each check-in.
Include the following information:
What this file is for. That's a very useful piece of knowledge and it's more important than anything else. You should tell the reader, why there is such a file, why did you group functions in a separate file/package/module and why they are used. Maybe briefly, one or two lines, but that should be there.
Legal stuff, if appplicant.
Leave the place for special commands of console editors, such as of Emacs.
Add special commands that your auto-documenting system requires.
Things things you shouldn not include are
Who created the file
When it was created
Who modified it the last time
When it was last modified
What was added by the latest modification
You can--and should--retrieve it via the version control system, where it's constantly and automatically kept up-to-date. Let alone that most of these points are just useless.
Who created the file
When it was created
Who modified it the last time
When it was last modified
What was added by the latest modification
Context: I work at a small software company that has traditionally done research-type work, and does not have much experience in the commercial space. We are now trying to push into the commercial world. Due to our origins in research we are used to a very rapid development cycle and very little structure in terms of maintaining proper versions of projects.
Problem: The lack of structure is now proving to be somewhat of a hindrance, as every developer has a slightly different view of the code base. A problem one developer discovers is not reproducible by another developer, and problems found in one build may disappear in the next (or worse, new problems may appear). This makes for a very frustrating experience for someone who is responsible for integrating all the projects and ensuring quality and performance standards are met - i.e. myself.
Potential solution: Personally I am convinced we need to enforce better structure via fixed version numbers and regular releases. It should be self-evident how proper versioning would help with many of our problems, but of course it is not without problems - developers need to do extra work to perform and test releases, and will no longer be able to use the latest versions of everything.
Question: To come to a point - what sorts of strategies do you recommend for ensuring the process and effort required for releases occurs as smoothly as possible? We are using git for version control, maven for our build system, and we have bug tracking and continuous integration systems running, so I believe the tools are there. I am simply unsure about what a proper release process should look like.
You have the big three in place: version control, one-click build via Maven and your continuous build server, and bug tracking. It sounds like you guys are gravitating towards Agile methodologies, and so you ought to be trying to keep the trunk version of your product in a near deliverable state at all times.
When you decide to make your first release, create a branch off of your trunk version for that release. Decide on a labelling scheme and be sure to label the branch version. For example, your first release could be 1.0.4530, where the 1 means first version, the 0 means it's the first release candidate, and the 4530 is the version control change number. You test this release branch and fix important bugs on it. After a while you issue another release candidate, say 1.1.4807. This process iterates a couple more times (say), your release becomes good enough, and you ship version 1.3.5167.
Meanwhile, your new development occurs only in the trunk version, and from time to time you'll need to merge bug fixes from the 1.x release branch back to the trunk. Later, you'll split off a 2.x branch from the trunk to repeat the process for your second release. You'll generally have several active branches (plus the trunk), with development limited to the trunk and each branch kept pristine and independent from development.
You guys will get the hang of things and your developer coordination problems will become less frequent. But these problems are nearly all going to be limited to the trunk, not the release branches.
A problem one developer discovers is
not reproducible by another developer,
and problems found in one build may
disappear in the next (or worse, new
problems may appear). This makes for a
very frustrating experience for
someone who is responsible for
integrating all the projects and
ensuring quality and performance
standards are met - i.e. myself.
Potential solution: Personally I am
convinced we need to enforce better
structure via fixed version numbers
and regular releases.
I don't think you need to have very frequent releases just to coordinate internally. You can do that through version control. Just have people talk about specific git revisions when reporting issues. Also note that you will have to coordinate any external dependencies/libraries too. Some kind of vendor branches could help with this.
It sound like the developers need to use "test branches" and respect the "stable/production branch" a little bit more.
Sell in the concept of "do your wild west stuff in this branch", and when you are happy with the results then you merge it into this "boring stable production branch"....
(or something like that)
There are books written about the general topic; Amazon search even returns three titles for specialized "version control with git."
I think you will benefit from defining a canonical view of the code base. Call it Test. A problem is a problem if it appears in Test. If a problem does not appear in some developer's view, it is up to that developer to figure out what is the important difference; and likewise for a problem that appears in a developer's view, but not in Test.
One convention is for Test to be re-built from sources on a nightly basis. A more strenuous convention is for Test to be re-built upon every update. If your team is small (five or fewer) and not dispersed over great distances or multiple timezones, a reasonable first approximation is to make Test a git workspace on a server upon which your toolchain has been installed along with some cron jobs so that this workspace is updated and rebuilt every night (usually).
Recently I've been revisiting an old project, which I last worked on about two years ago. Obviously, during this time I've learned new habits about how best to program, and I've got the itch to keep the tests, scrap the implementation, and re-implement the entire project. It's not a large project, and I believe I'll not be losing much by re-writing it.
However, I don't know what to do about the version history. It's likely that when I'm done updating it, the new version will share only 3-4% of its code with the old version. Furthermore, the changes tend to be so wide-reaching that trying to maintain clean changesets is an exercise in frustration and futility. Given this, it seems unnecessary to force potential developers to download the old irrelevant versions.
One option I've been considering is to move the trunk to a branch, something like old-trunk/, and begin development in an empty branch. I don't know if this is a good idea, and I'm concerned that having two trunks could lead to confusion. Which brings me to the question:
What does SO think? If you encountered a project that had "reset" its trunk, would you be confused by it?
Why not just label/tag the trunk with "OldVersion" and continue development in the same location? This way you avoid the double branch altogether and still maintain ways to get to the old version of your code. Unless you're developing a different product, you likely want to keep the same trunk.
I tag the $trunk, so there is a "copy". Tag it the last version released, or the date before you started back on it, etc. I actually tag on the date released, and name my tags the actual date itself. (use Label inplace of tag if that is what your system supports).
After it is tagged, delete/rename/overhaul as needed. The version history is there, just in case. And, you have a complete copy labelled/tagged for archiving purposes.
Assuming you're using SVN, there's really nothing extra to do. Just remember the revision from which you started refactoring and then continue in working on the trunk. It's better than moving to an empty branch since the history of the changes from the old code to a new one will be recorded.
However, if you plan to write the thing from scratch and just copy some little bits of old code, maybe you should think about starting it in a new repository.
I don't see the need to throw the old version away. Just make all changes and check in. New developers will not have to download any old code, they will always just check out the new version.
No, it wouldn't confuse me because the project documentation would show that before I even got into it. We ALL have crap that needs to be redone, and frankly, should be.
Tell everyone it's insecure and not HIPAA compliant and they'll let you re-code it ;o)
And then start posting the fodder onto The Daily WTF for the rest of us 80))