Jump to content
  • Checkout
  • Login
  • Get in touch

osCommerce

The e-commerce.

Documenting Changes


Dan Cole

Recommended Posts

Sometime this year I'm going to upgrade my RC2.2 site to 2.3.3.4 and (I think) I would like to do a better job of documenting the changes and contributions that I'm going to install. I've probably added hundreds of contributions and hacks over the years and while I'm not going to focus on what I've done in the past, I'm thinking I should really have some organized way to record the changes and addons that I'll be making to the 2.3.3.4 version. I don't want to turn this into a make work exercise but I can't help but feel that it should be documented in some way so I'm wondering what everyone else does. Do you have an organized way to record the changes you make? Is it worth the effort involved? Any input would be appreciated.

Link to comment
Share on other sites

@@Dan Cole I had exactly the same idea when I elected to update and I documented the changes here:

 

http://www.oscommerce.com/forums/topic/395359-modding-up-a-new-2334-install-documented/

 

The reasons for doing that were 2 fold:

 

1) To try to help others who were upgrading

2) To give me a documented sequential list of actions in case I needed to back track.

 

I also gave all my backups (of files and database) sequential numbers starting at B1, B2 etc and created a notepad document stating what the backup was prior to doing eg. B20 backup prior to installing X-sell etc etc.

 

I also kept a clean copy of 2.3.3.4 on my local machine in case of severe accident.

 

I also kept 3 Backups of my old store (local machine x 2 + a memory stick) just in case things went horribly wrong.

 

It took me about 3 weeks in all, but not too bad and now looks and works great with just 2 minor glitches that I cant seem to sort at the moment

 

God Luck!

Now running on a fully modded, Mobile Friendly 2.3.4 Store with the Excellent MTS installed - See my profile for the mods installed ..... So much thanks for all the help given along the way by forum members.

Link to comment
Share on other sites

@@burt How about a new forum heading for Update threads documented? that way they wont get lost in the noise?

Now running on a fully modded, Mobile Friendly 2.3.4 Store with the Excellent MTS installed - See my profile for the mods installed ..... So much thanks for all the help given along the way by forum members.

Link to comment
Share on other sites

I'm not sure that a specific list of your changes would be useful for other store owners, except as an example or two of how to track changes. After all, for add-ons it's just a matter of keeping a list of what you installed, of what version, and in what order. For any custom work (including add-on installs that needed manual coding), that's where you need a system to track it. If you do your work all in one pass, you can preserve a "before" snapshot and do a diff (Linux) or fc (Windows) against the finished files to document what you changed. In some cases, that might even work as input for a "merge" program (to update a later version). For work intermixed on several projects and add-ons, that might be too confusing, leaving you only with doing a manual log of changes and in-code markers. Of course, the manual logging requires the discipline to record everything as you go, lest you forget something. And in the mad rush to fix a serious bug, you're bound to forget all the changes you made. In that case, preserving a site-wide "before" snapshot (could be your regular backup) and diff'ing the whole thing might work.

 

If your chief concern is being able to "roll back" changes, you might want to look at various source versioning systems, such as Git, SVN, CVS, etc. Unfortunately, they are more oriented towards being able to roll back changes and to branch versions, than migrating all your changes from one base to another. Maybe such a system exists that would let you mark certain changes as "installed by add-on" (ignore them), and let you mark/version custom code changes, and let you apply them to future code bases? That could be interesting and useful. Has anyone heard of such a system?

Link to comment
Share on other sites

@@Dan Cole I had exactly the same idea when I elected to update and I documented the changes here:

 

http://www.oscommerce.com/forums/topic/395359-modding-up-a-new-2334-install-documented/

 

Thanks Heather. I actually followed along with your thread and the process you when through to do it. It was interesting and probably is responsible for my thinking about what I should be doing as I go through the upgrading process....yes that's it....it's all your fault. :)

 

Seriously though, like you I want to give back to the community and help others. I'm still not sure what I want to do or how I will proceed but that is certainly one of my motivations. I guess the other thing I was thinking was if I invested a little more time in organizing it I might save myself some effort the next time I need to do this but on the other hand that work might well be of little value when the time comes to go from 2.3.whatever to 2.4. Had you pondered that aspect of it as well? ie will documenting it really be of any use to me in the future?

Link to comment
Share on other sites

@@Dan Cole - woudl be awesome to have another upgrade thread. You might use entirely different approach to @@Mort-lemur and loads could be learned from both threads.

 

Thanks for replying Gary. I will probably do that just to try and give back. Still thinking on it. I'm no programmer but some folks on here might get a kick of my ability to cut and paste. :)

Link to comment
Share on other sites

I'm not sure that a specific list of your changes would be useful for other store owners, except as an example or two of how to track changes. After all, for add-ons it's just a matter of keeping a list of what you installed, of what version, and in what order. For any custom work (including add-on installs that needed manual coding), that's where you need a system to track it. If you do your work all in one pass, you can preserve a "before" snapshot and do a diff (Linux) or fc (Windows) against the finished files to document what you changed. In some cases, that might even work as input for a "merge" program (to update a later version). For work intermixed on several projects and add-ons, that might be too confusing, leaving you only with doing a manual log of changes and in-code markers. Of course, the manual logging requires the discipline to record everything as you go, lest you forget something. And in the mad rush to fix a serious bug, you're bound to forget all the changes you made. In that case, preserving a site-wide "before" snapshot (could be your regular backup) and diff'ing the whole thing might work.

 

If your chief concern is being able to "roll back" changes, you might want to look at various source versioning systems, such as Git, SVN, CVS, etc. Unfortunately, they are more oriented towards being able to roll back changes and to branch versions, than migrating all your changes from one base to another. Maybe such a system exists that would let you mark certain changes as "installed by add-on" (ignore them), and let you mark/version custom code changes, and let you apply them to future code bases? That could be interesting and useful. Has anyone heard of such a system?

 

Thanks Phil...I guess what I've really been struggling with here is whether there is anything I can do as I go through this process that might be of help to either the community or indeed to myself if or more likely when I need to upgrade again...I'm coming to the conclusion however that this might well be a one time effort and that I should perhaps treat it as such and not get to hung up on documenting it, at least not for my own purposes anyway.

 

Thanks for taking the time to post...I will continue to wrestle with this for now.

Link to comment
Share on other sites

Any custom coding (non-add-on changes) should be thoroughly documented -- not only exactly what changes were made, but also why each particular change was made. Several years from now, when you update your base code again, you need to know why so that if necessary you can reconstruct what you did, in case the underlying base code changed enough that you can't directly apply your old changes. The new base code may even have your changes more or less built in (i.e., you don't need to put your changes in).

 

It's best to document changes as well as you can, so that you won't drag your feet on upgrading to 2.4 or 3.1 when they come out, and it won't be so painful because you don't have to remember all the things you did and have to re-invent them. Never plan on it being a "one time effort", unless you know that you'll be permanently shutting down your site within a few years.

Link to comment
Share on other sites

I had hardly any documentation in my 1st 2.2 store - which was built originally by 3 different people until I took it over. And even though I upgraded last June I still didn't document well enough.

 

During the upgrade to 2.3.3 I //commented// in the files where I made custom changes, saved backups after every change and named each backup (backup "data" before sppc & backup "data" after sppc) but in retrospect I wish I can made more thorough comments.

 

As @@MrPhil said... moving into 2.4 and beyond, as a store owner managing my own code, if I had spent the extra time documenting better I would have been less "stressed" about the future.

Link to comment
Share on other sites

I tried to document all addons added to my test store. Guess what. It all went wrong. I have a folder with the saved addon downloads in. I have a list of which addons were added and in which order. I also have some amendments that needed to be made. I all went wrong when I was searching the oscommerce forums and found useful snippets of code, which I added, and forgot to document. It is now a question of trying to remember what I did, and what file I did it to.

 

I did upgrade my test store as the latest version was released, and I started again, and I have managed to get it nearly as it was, but there are still some parts that need alterations. I do have the original code, so its just a case of finding where alterations were made.

 

I guess what I am trying to say, is that no matter how good and careful you are with documenting what you do, there will be times when you forget.

REMEMBER BACKUP, BACKUP AND BACKUP

Link to comment
Share on other sites

Thanks folks....I'm still rolling this around but for the smaller tweaks and hacks that I make along the way, I'm leaning towards developing a system that will involve my making changes to the base code using <include files> and an organized method of naming both those include files and using a directory structure to create a systematic way of documenting things. Those tweaks or hacks usually only involve a few lines of code which seems to lend themselves to this type of approach and I know if I don't create a systematic way to handle it, it simply won't happen.

 

Anyway I'll give this a shot and see what problems develop. I tried it with a change I was making yesterday and I rather liked the process since it kept me focused on the task and code at hand although my initial choice of file names and the directory structure needs to be though through a bit more. I was trying to mimic the directory structure used by osC but I'm not sure that is the best approach. It does serve to document what files were changed but I can see that making multiple changes to the same files will become problematic. As I said I'll need to think about this some more.

 

For the more involved changes and hacks I think I'll treat those as contributions or add-ons and take a logging approach (like Heather did) to document those and then store the zip files once they are installed, in a separate directory, to serve as a list of what was added, when etc. Hopefully I can be disciplined enough to manage that.

 

As always I'd welcome any additional comments or suggestions you might have.

 

Dan

Link to comment
Share on other sites

  • 5 months later...

With all the excellent work done by @@burt on the bootstrap version I thought I would start on updating my site...it is currently running on RC2.2a (I think that's right) and I've added tons of additional function that has been contributed by the community and other tweaks that I added over the years..some that I liked and worked well...some that never worked at all (I probably didn't follow the instructions well enough). At this point, I'd describe my site as heavily modified with lots of function I don't need or use but all in all it works and certainly serves me well. With that said, I see the value in upgrading especially to the BS version as more and more of my traffic is coming from mobile devices.

 

My plan is to document my journey here in the hope that it would be of use to others who are updating their sites...I've been working on it over the last couple of weeks so I'll probably add updates on a regular basis at first and as I catch up my rate of progress/posts will likely slow to a crawl as I get hung up dealing with other day to day issues. My plan is to work with my existing database so I'll be making the necessary SQL changes so it works with both my RC2.2a and 2.3.3.4BS sites. In other words my plan is to alter my database so it works on both my existing site and my new site so I can just move a copy of my database over to my new site, or simply change the configuration files, when I'm ready to go live with my BS site. I'll also try to answer questions as I go along.

 

For the moment, that's the plan...

 

Dan

Link to comment
Share on other sites

A lot of the configuration is stored in the configuration table in your database, so your old store will fail as soon as you try  to configure something in the new store that doesn't exist in the old store. You need two databases.

 

Regards

Jim

See my profile for a list of my addons and ways to get support.

Link to comment
Share on other sites

You're spot on as usual @@kymation. I learned that the hard way...after I copied my existing database over and updated it to use 2.3 I couldn't get it to work and didn't know why....after thinking about it for a bit I figured it was the configuration table so I added the new 2.3.3.4BS configuration table to the database and away it went. A few days later I realized that my old RC2.2a test site was no longer working and that I needed the old configuration table in order for it to function...I guess I could have used a separate database as you point out but instead I decided to run with two configuration tables and specify which one to use in the database_tables.php file. In other words I set up two configuration files one for use with my old RC2.2a site and the other for the 2.3.3.4BS site. That seemed to have solved the problem but I did run into (as @@burt would say) a poorly coded contribution that made a direct query against the configuration table instead of using the table name definition as specified in the database_tables file. Hopefully this approach won't cause any other problems that I haven't anticipated or that hasn't raised it's ugly head yet.

 

When I get a chance I'll post about how I went about getting my RC2.2a database to work with Garys Bootstrap version.

Link to comment
Share on other sites

@@Dan Cole

Cool ! It looks like I'm not the only one doing funny things in database_tables and configure.php files

My efforts have been to show different subsets of data using database views and/or filters coded into the configure file of the particular store.

KEEP CALM AND CARRY ON

I do not use the responsive bootstrap version since i coded my responsive version earlier, but i have bought every 28d of code package to support burts effort and keep this forum alive (albeit more like on life support).

So if you are still here ? What are you waiting for ?!

 

Find the most frequent unique errors to fix:

grep "PHP" php_error_log.txt | sed "s/^.* PHP/PHP/g" |grep "line" |sort | uniq -c | sort -r > counterrors.txt

Link to comment
Share on other sites

@@Dan Cole

Cool ! It looks like I'm not the only one doing funny things in database_tables and configure.php files

My efforts have been to show different subsets of data using database views and/or filters coded into the configure file of the particular store.

@@bruyndoncx

 

That is comforting Carine. I was a bit worried that what I was doing would jump up and bite me at some point. From your posts I know you know your way around a database so that is comforting indeed. Thanks for mentioning it.

Link to comment
Share on other sites

  • 2 weeks later...

It's raining here today so it's a good time to explain the steps I took to get a my 2.2RCa database working with 2.3.3.4 Bootstrap version. The first time around I didn't necessarily do things in this order but it's what I would do now knowing what I now know and learned along the way.

1. First I downloaded and installed 2.3.3.4 BS on my test server which also uses a test database.  Be sure you don't over write your existing database -- the installation will create a new 2.3.3.4 database and your previous data will be lost.  Fortunately this is one thing I didn't have to learn the hard way.

2. Since I wanted to use the same database for both my 2.2RCa site and my new Bootstrap site I copied over the configuration tables from my old 2.2RCa database, renamed them to configuration_r2 and configuration_group_r2.  I then specified that I wanted to use these configuration files for my 2.2RCa site....defined as follows in my database_tables definition file.

  define('TABLE_CONFIGURATION', 'configuration_r2');
  define('TABLE_CONFIGURATION_GROUP', 'configuration_group_r2');

At this point I'm not sure if I actually needed to do this for the configuration_group table but did so out of an abundance of caution and it was simple to do, so I did it.  This allowed me to have a different configuration file for both my sites -- as I learned the hard way the old version of the configuration files would not work with the new site and vis-a-versa.

3. Next I downloaded a backup copy of my 2.2RCa operating database. I then unzipped it and uploaded a copy to an area on our site where I could use MySQLDumper to restore the backup to my test sever.  Our database is too large to be restored in any other way I've stumbled upon so far. Its probably worth noting here, and I found this out the hard way, that MySQLDumper will drop all tables before restoring the database so unless your backup contains both versions of the configuration files it'll trash them and only restore the ones that exist in your backup database.  My approach here was to add the second copy of my configuration files to my working database so that both versions would be backed up on a regular basis and could be restored as needed.

4. The next thing I did was to run the sql queries in the contribution "SQL upgrades from 2.2MS to 2.3.3" that can be found in the add-ons area to update the database to work with 2.3.3.4 and volia I now have a database that can be used on both my working 2.2RCa site and that can be used with my new Bootstrap version.  

Now the real work begins as I try to sort out the various contributions I've installed on my 2.2RCa site over the years and change those that I want to keep so they work with my new Bootstrap version.

Link to comment
Share on other sites

  • 3 months later...

Hi Burt. That is indeed one of our ancient sites...I do have a BS version up and running but I'm bogged down needing more time to add contributions, product etc. Coming into our busy time of the year. I need to find a way to get more hours in the day.

 

When I get the BS version to where I want it I'll begin to replace those ancient sites but in the meantime I'm just making do.

 

Thanks for asking...

Link to comment
Share on other sites

Archived

This topic is now archived and is closed to further replies.

×
×
  • Create New...