If you and other members of your team spend serious amounts of time building or maintaining traditional Domino applications (i.e. you use Domino Designer), then you’ve almost certainly grappled with the issue of how to implement source code control in the Domino environment. And if you’ve done that, then you’re probably familiar with Teamstudio CIAO! - the world’s only source control system specifically designed for traditional Domino apps.
When it comes to Source Code Management and Version Control systems, there are two main types of tooling: distributed and centralized systems. We have written about this in a previous blog post: Centralized vs Distributed Version Control Systems - What's Best for Notes Development? In that post, we talk about why we think centralized systems are the way to go for traditional Domino development. And, like conventional SCM systems such as CVS and Subversion, Teamstudio CIAO! fits into that category. However, these conventional 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 Domino database design, because all elements of a Domino database’s design are held in a single file.
Of course, it is possible to use the Source Control Enablement feature in Domino Designer 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 traditional HCL Domino, you have to be a bit careful about how you implement a version control system. With that in mind, here are a dozen tips that should prove useful to anyone using Teamstudio CIAO! in their day-to-day work.
1. Databases under CIAO! control should be considered the primary copy of a database's design.
Anything else is not to be considered 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 prior to that.
In our experience, many organizations will consider the design in the production database to be the primary copy of the database design. They would 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 should be documents (if needed) for testing purposes.
2. All design changes, however trivial, are made on a dedicated development server, never on a production server.
Changing a view column to extend to window width is a trivial change with no bad side effects. So why should this be done in development? There are several reasons for this. First, see tip 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 typically 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 than sending out an email every time you add a sort order to a column.
Finally, sometimes things don’t go as planned. Have you ever created a database with documents no can read because of broken reader fields? Then you know what we’re talking about.
3. Use an NSF to develop applications, not an NTF.
On the development server, 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, using an NSF allows all scheduled agents to run, and allows design elements to be previewed in a web browser, if necessary.
This also simplifies your development environment. The practice of using a template in development and updating the development database leads to issues such as developers ‘finalizing’ agents in the database, then copying and pasting them 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 creating that version of the design element.
The same goes for databases. There is a copy of the database design that can easily be restored in case anything goes wrong. There is no need to create another copy of the database that needs to be managed.
5. Don’t forget to save versions of design elements and databases.
It is possible to 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 check in 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 application design 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 if you followed tip 5, 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. There is no such thing as too many versions of design elements.
CIAO! lets you develop very incrementally. When you get a feature 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 feature, 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, (as many of us do these days), is okay. But it’s best to check out any design elements you might change while working remotely. 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 tip 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:
ForceConfigLocation=111. Use VMs to improve network connectivity if necessary.
If you have distributed teams with low bandwidth connections to remote development servers, set up a Virtual Machine 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 we often call 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.
We hope you found these tips helpful. If you have more questions, or feedback on this or any other aspect of the Teamstudio developer tools, click below to start a conversation. We love to chat!