The mechanics of using Teamstudio CIAO! are pretty straightforward after it is properly configured. But there are some areas where experience has shown work habits that can maximize the benefits of using CIAO! In this blog post, aimed at CIAO! users, we've gathered together a dozen best practices that, if you adopt as habits, should deliver significant benefits.
CIAO! provides full Source Code Management (SCM) and Version Control for Lotus Notes/Domino application designs. Conceptually, it is comparable to conventional SCM and Version Control systems such as Git and Mercurial. These systems work on the basis of controlling access to individual source code files and managing versions of those files. This will not provide a satisfactory solution for a Notes database design however, as all elements of a Notes database’s design are held in a single file.
Of course, it is possible to use the Source Control Enablement feature to manage an NSF as a collection of DXL files, but in our experience many users find it overly cumbersome and hard to configure and use correctly. Plus, it's not much help if you end up needing to merge changes to traditional elements like Forms and Views.
CIAO! permits control at the design element level. This means that each individual form, view, page, script library etc. can be independently controlled and will build up its own history. The overall design of the database can be versioned and assigned a unique number, allowing a specific configuration of design elements to be uniquely identified.
Because of the unique nature of software development in Notes/Domino, you have to be a bit careful about how you implement a system like CIAO! With that in mind, here are 12 habits that should prove useful:
1. Databases under CIAO! control should be considered the ‘gold’ copy of a database's design.
Anything else is to be considered not trustworthy – without an audit trail of changes there is no way to verify what has happened to a database design. Consider the situation where an agent schedule is changed to run at a different time, and then a day later changed back to the original time. You only have evidence of who made the last change, not all the changes (and reasons for changes) made before.
The biggest change as a result of this habit is what used to be considered the gold copy before implementing CIAO!. Frequently, organizations would just make a copy of the database from the production server (documents optional) to the development server. But once the database is put under CIAO! control, the only thing copied from production is possibly documents for testing purposes.
2. Design changes are made only on a development server, not a production server.
Otherwise, where do you draw the line? Changing the view column to extend to window width is a trivial change with no bad side affects. So why should this be done in development? There are several reasons for this. First, see habit 1 above. When changes are made to the production server, there is no audit trail. The version in production doesn’t match what’s in development, and turning on "prohibit refresh" prevents future changes from the template to update the application.
Second, users don’t like constant changes. Really. Save up all those changes for a single ‘release’. This gives you a chance to explain all the changes at once, rather sending out an email every time you add a sort order to a column.
Finally, sometimes things don’t go as planned. If you haven’t created a least one database with documents no can read because of broken reader fields, you may not be taking advantage of a key feature of Notes!
3. Develop applications using an NSF, not an NTF.
On the development server, simply use an NSF file for your development. This is the database to put under CIAO! control. There are several reasons for this. First, a template or NTF will be created when the design is promoted to the testing or QA environment. Second, this allows all scheduled agents to run, and allows design elements to be previewed in a web browser, if necessary.
This also simplifies the development environment. The practice of using a template even in development and updating the development database leads to developers ‘finalizing’ that agent in the database, then copying and pasting it back into the template. Which leads to design elements being modified without being checked out. Which in turn leads to multiple developers making changes to the same element, or lack of versions, and no audit trail. The fewer files that need to be controlled, the better.
Include the use of test documents. It is a development database, so any data in it is for test purposes. Multiple developers can share test data. Yes, you should have a mechanism to restore the data to a known starting point, but this is a different issue than controlling code development. Teams of developers have said they want to be sure some other changes don’t impact their changes, and they need their own test data. At some point, your changes are going to have to be tested in conjunction with other developers' code. The sooner you do this, the better. And the best way to ensure this is by developing in the same NSF, which is a key feature of CIAO!.
4. Let CIAO! manage design element and database versioning.
Every time a design element is checked in, CIAO! makes a copy of that version of the design element. There is no need to make a copy of the design element ‘just in case’ something goes wrong, so don't do it! Likewise, making copies for archival or historical purposes is not necessary. Each version includes the date and time as well as the developer's name and the reason for that version of the design element.
Similarly for databases. There is a copy of the database design that can easily be restored in case design changes go horribly wrong. There is no need to create another copy of the database that needs to be managed.
5. Make versions of design elements and databases.
You could check out a design element and leave it checked out forever. You could even refresh a database in production with checked out design elements with no effect on the functioning or performance of the application. But that’s not why you implemented a source code control system. If your only option for rolling back to a previous version is the one you started with two years ago, you haven’t really increased your productivity! In fact, you should make versions of your design elements whenever you have a known, working version. Even if you have more changes planned. Especially if you have more changes planned. These interim versions allow you to roll back to something that worked. (Use the check in option ‘keep checked out’ to easily create an interim version while you're working.)
For databases, make a version every time the database leaves the development environment.
This allows better tracking of what was tested, what was put into production, etc. It also makes it easy to roll back changes to many design elements in one process.
6. Use database versioning to make hot fixes.
A Hot Fix is a high priority change to the production database that must be made quickly. And in typical development environments, the version of the database currently in development has partial enhancements made to it that are not ready to be deployed.
But there is a version of the code that was last sent to production in the CIAO! log file. Simply get that version, make your fix to it, and redeploy that version. (See the CIAO! User Guide for more specifics on how to do this). This version does not need to be under CIAO! control, because you are going to make the same fix to the copy in development that is under CIAO! control. Thus providing the audit trail and versioning of the design element that you require.
7. Check in design elements as soon as you are done with them.
First, no one else can make changes to that element while you own it. Secondly, it is too easy to make more changes at a later date, with no interim version of the first set of changes.
8. You can never have enough versions of design elements.
CIAO! lets you develop very incrementally. When you get a piece of functionality working correctly in an agent, but need to further extend it, check in the design element, but keep it checked out. The check in creates a version of the element with known, working functionality. If something happens when adding the additional functionality, the previous version is always available to roll back to. Particularly when working with xPages. These tend to get really broken, really quickly.
9. Working remotely is okay.
Working from home, or in a hotel room, is okay. But you do need to check out any design elements you might change while working remotely. See habit 6. In order for all developers to know what design elements are checked out, all developers must check out design elements on the same database on the development server. Once checked out, the database can be replicated locally. Once working locally, see habit 5 – do not make changes to design elements you have not checked out. Sure you can change them and maybe replicate them back to the development server, but if someone has checked it out in the mean time, your changes will be blocked. Or, even worse, if someone checked it out, made changes, and checked it in, your replication will overwrite anything they did.
10. Each configuration file should only contain databases on that server.
For really distributed teams, each development server should have its own configuration file - and definitely not a replica. If you need to work on a database on another server, go to that configuration file to find the database. To ensure this, the client should be configured to use the config file on the server where the database is located. You can also do this by making sure this line is in the [CIAO] section of your Teamstudio.ini file:
11. Use VM’s to improve network connectivity if necessary.
If you have distributed teams with low bandwidth connections to remote development servers, set up a VM or remote console connection on a locally connected workstation. The remote developers connect to this workstation to check out any necessary design elements on the common server. Of course, the remote developer still needs their own license of CIAO! for local development.
12. Use one log file per ‘application’.
Despite the fact that Notes calls a database an ‘application’, we know that your application may be made up of several databases. In order to track the history of that application, use one log file for all those databases. When the file becomes large, or after a major release, you can archive the history for the version before the prior version. For example, if you just released version 3, you can archive the history for version 1.
If you want an easy way to track what changes you make to many different databases, use one log file for all your databases. Then, you manage the size by archiving history for the prior year, as an example. This allows you to go to one place to document what changes were made.