How to document changes?

[ezypezy80]

I'm a junior in IT dept and going nuts trying to keep track and remember changes I made to softwares
Most of the time, customers enquires some bits and pieces to be changed on the initial specs.
I keep versions of software but definitely forget what I've done on which version. And then will get even mesier
when I dont remember which version I actually loaded on site.
There must be an efective way on organising this. Really need advice in documenting techniques.

thank you

 

[sleipnir214]

Sounds to me like you need to use revision control software.

Want the best answers? Ask the best questions:

http://www.catb.org/~esr/faqs/smart-questions.html

TANSTAAFL!!

 

[CajunCenturion]

Here are three ideas for consideration, all of which have value, expecially when used together.

Establish a directory structure to keep track of the project.

ProjectName
Version0100 ' Version 1.00
SourceCodeFiles
Version0101 ' Version 1.01
SourceCodeFiles
Version0201_Loaded ' Version 2.01 (Loaded)
SourceCodeFiles
Version0202
SourceCodeFiles ' Version 2.02
...

Secondly, document the code in line with one or two quick lines:

<executable code>
/* ezy-08/28/03: Made this change to allow for whatever it it */ (BTW 'ezy' are the initials of the programmer)
<continue with code>

Thirdly, maintain a master document where you keep track of what was done when, by whom, and to which version, organized similar to the directory structure above, replacing the SourceCodeFiles with written text about who, when, what, and why any routine was changed.


Another side advantage of the directory structure approach, especially if multiple versions are in operation (ie a product situation), is then when a bug is found in one version, you can easily walk the bug fix forward through the other version.

Good Luck
--------------
As a circle of light increases so does the circumference of darkness around it. - Albert Einstein

 

[dilettante]

Even keeping a running change log would provide something.

Many programming environments offer some way to enter a version number (major.minor.patch as in 2.3.0013) that will &quot;stick with&quot; the source. Worst comes to worst you can just hard-code your verion someplace, say as a constant.

Then, also someplace where it'll stick with the source such as a source module that is all comments if you have to, record your changes. I'd suggest a minimum of:

Change date
Version
Change description text

It might be worth making a separate log entry when you &quot;release&quot; a certain version, even if it is made up of several separately numbered changes.

Depending on the type of software it may also make sense to record changes in the user documentation in the form of a change history. What you say here will be different because it should briefly describe how the software &quot;looks different&quot; and &quot;acts different&quot; in a new release, from the user's perspective.

While those source-level comments may serve as reminders, you might want a more extensive supplemental change document where changes are described in more detail for each change. Often I include the bug description or user request for each change here. Things such as file format changes or function call changes or property & method call changes ought to be spelled out in detail. UI changes may benefit from screen shots even. Pick a level of detail that works for you and doesn't increase your development time astronomically.

I agree that version control software can help a lot on larger projects. Even smaller ones can benefit because most of these tools will make it easier to &quot;back out&quot; changes if you need to later on.

In any case it is always good to create a file archive of any released version of software. I usually create a zip file with all source and developer documents, and a second one with all of the &quot;deployables&quot; (code, help files, table or parameter/ini files, etc.) and any user documentation not already embedded in the product. I burn these on CD-RWs as well as keep them on a backed-up file server. When I have enough accumulated I burn a CD-R and make an extra copy.

If you use bug-tracker software and version control you can modify the basic idea. As you have found it is useful to have change history in case things go wrong (or even if somebody wants to know &quot;what the heck&quot; you've been doing).

Dates and version numbers are very helpful in general though. Especially if you can interrogate the binary product and determine its version (even if only in a &quot;Help > About&quot; box or a component's &quot;version&quot; property).

 

[chiph]

Do you do parallel development, where you're making changes to multiple versions at the same time?

If so, skip Visual Source Safe, and go to something like Perforce or StarTeam. These products will allow you to do this, and help you merge your changes back into your code baseline. This way your v1.1 product will get the bug fixes that you make in the v1.0 release.

Chip H.


If you want to get the best response to a question, please check out FAQ222-2244 first