Version Control with twinBASIC in 2024

Version Control with twinBASIC has gotten much simpler since I last wrote about it:

That article was written only a few months after the initial alpha release of the language.  At the time, you had to rely on command line switches to translate from a single binary .twinproj file to individual text files and back again.  For quite some time now, that functionality has been properly incorporated into the twinBASIC IDE.  I'm just now getting around to writing about it.

Overview

A twinBASIC project is stored within a single binary file (the .twinproj file).  

To work with version control, the single binary file must be split into individual text files.  To resume developing in twinBASIC, those text files must be reconstructed into the single binary .twinproj file).  

This is very similar to how Microsoft Access version control addins work:

Conceptual Overview

At a conceptual level, the process is still very similar to what it was nearly 3 years ago:

• Export from .twinproj to individual text files
• Commit the text files to version control
• Import from text files into a new .twinproj file

Practical Overview

At a practical level, the process is much simpler:

• Enable automatic export on save in project settings
• Save the twinBASIC project (the exported text files update automatically)
• Commit changes to version control
• Use [Import from folder...] to build a new .twinproj file from source on a remote machine

Step-by-Step

Here's the step-by-step process that I tested for my upcoming DevCon Vienna 2024 presentation.  

NOTE: I prefer Mercurial to Git, and these instructions reflect that.  But most of these steps are version control system-agnostic.  The few steps that are system-specific (like excluding binary files from the repository) should easily translate to Git-equivalent commands.

Your file paths will obviously be different than mine, but I find tutorials easier to follow when they use actual paths rather than placeholder text.

Create an empty repository

Create a new Mercurial repository in a folder named "DevCon2024":

M:\Repos\NLS\DevCon2024\.hg\

Open the twinBASIC IDE and choose Sample 4:

Name the project DevCon2024:

Save it in the repository folder we created above:

M:\Repos\NLS\DevCon2024\DevCon2024.twinproj

Edit the .hgignore file to exclude .twinproj files from the repository:

.hgignore contents

syntax: glob
*.twinproj

Perform an initial commit with the message, "ignore tB project files."

The only file that should be included in the commit is the .hgignore file.  Most importantly, the .twinproj file itself SHOULD NOT be committed to version control.  

We will commit the individual text files that comprise the .twinproj file momentarily.

Set Export Path for Version Control and Perform First Export

1. In twinBASIC IDE, go to Project > Project Settings...
2. Search for "export" in the Project Settings window
3. Check the box next to "☑ Project: Export Path"
4. Enter text: ${SourcePath}\Source
5. Check box next to "☑ Project: Export After Save" and set value in dropdown to Yes
6. Click [Save Changes]
7. File > Export Project… to force an initial export
8. In TortoiseHg, commit with the following message: initial export from twinBASIC IDE

Some notes about this initial commit:

• The project export path of ${SourcePath}\Source will save the twinBASIC source files to a subfolder named "Source" in the same folder as the .twinproj file itself.
• This first commit will include over 1,000 files; this is expected.
• Most of the committed files come from referenced packages; that's ok.
• Remember, "Anything that can lead to a bug in our software belongs in version control."  For twinBASIC, that includes the contents of any referenced twinPACK packages.

Test Build From Source in an Empty Folder

This next set of steps builds a .twinproj file from source files.  

This is the process you would follow on a new development machine, or if you cloned a twinBASIC repository from a colleague or other developer.  Rather than use a different machine, though, we will create a clone of our repository in the user temp folder on the same machine.

Also, we store our master repositories on an Opalstack shared web server.  If GitHub serves that role for you, you'll want to replace any references to "opal" or Opalstack with GitHub equivalents.

1. Create a new folder: %tmp%\DevConClone\
2. Clone the repository into this folder:  hg clone --verbose ssh://opal//home/gb/repos/devcon2024/ "C:\Users\Mike\AppData\Local\Temp\DevConClone"
3. Open a new instance of twinBASIC
4. In the _| New |_ tab, click [Import from folder…] then [Open]
5. Enter folder name: %tmp%\DevConClone\Source then [OK]
6. File > Save Project As… > %tmp%\DevConClone\DevCon2024.twinproj > [Save]
7. Make any small change to a project file
8. Save the project
9. Commit the change and push to Opalstack

Test Build From Source for an Existing Project

The above section covered the process of setting up a new development environment for a twinBASIC project.  

But what about the scenario where you already have a dev environment set up, but you need to incorporate changes to the project from another machine or another developer?

1. In the original repository (M:\Repos\NLS\DevCon2024), pull changes from Opalstack
2. Open a new twinBASIC instance OR go to File > New Project…
3. In the _| New |_ tab, click [Import from folder…] then [Open]
4. For folder, enter M:\Repos\NLS\DevCon2024\Source then click [OK]
5. Go to File > Save As…
6. Save project as M:\Repos\NLS\DevCon2024\DevCon2024.twinproj
7. Click [Yes] when asked to replace the existing file
8. Confirm that the project successfully built from source:
9. Go to File > Export Project… to force a full export of the source files
10. Verify that new "Last Modified" dates have been created in M:\Repos\NLS\DevCon2024\Source\
11. Verify that there are no pending changes in the repository

Future twinBASIC Improvements

Keep in mind, twinBASIC is still in its beta phase.  These are only interim instructions.  Future versions of twinBASIC and its IDE will simplify this process even further.  Here are some expected and/or proposed feature improvements:

Near-Term Improvements

I think a nice feature to add to twinBASIC would be a "Rebuild from Source" menu item.

The feature would work by first saving a backup of the current .twinproj file, then running the [Import from folder...] code using the folder saved in the "Project: Export Path" settings, and saving the resulting .twinproj file with the same name as the original project.

Long-Term Improvements

Eventually, twinBASIC will add support for external source files.

When that day comes, the .twinproj file can be treated more like a VB6 .vbp or other similar "solution" files.  The source files will be able to live as text files outside the .twinproj file and the export/import dance I described above will no longer be needed.

Looking out even further, I expect that Git support will one day be built right in to the twinBASIC IDE.  

Unfortunately, I can't say the same for my beloved Mercurial.  Losing has consequences.