Port: A VCS-agnostic and project based Studio source control tool

Greetings all.

I present you my project: Port.  

A (really) late-to-the-party VCS agnostic and project based source control for Studio.

 

I started this project several months ago when I noticed that most of the Studio's source control implementations weren't project based thus forcing the user to export/import all projects at once.

By taking a project based approach I noticed that quite some powerful advantages could be introduced, I'll just list them straight from the repo (that, by that way, is exported using Port):
 

  • Development and organization: Development and versioning is kept within the project scope.
  • Tests: Allows the code to be tested atomically within the same project (which means no ^UnitTestRoot usage).
  • SourceControl integration: Seamlessly exports the active item when saved. No need to check-in/out items manually.
  • Synchronization: Keeps your repository in-sync with the project. Removes extraneous items when exported.
  • Smart backup: Mirrors the application directory and backups only what is changed inside the project.

 

If you browse the repo, you'll notice that Caché files are appended with an .txt extension, that's only to stop Github from tagging the languages wrongly. This behavior can be disabled using the bult-in Wizard.

Please be warned that  I'm not posting this project exclusively for divulgation, but I think that some few ideas could be brought with the next Atelier releases.

Even though 2015 version might work, I recommend using it along the 2017 version.

Thanks for your patience,
Rubens.

 

  • + 3
  • 0
  • 177
  • 4

Comments

Hi, Rubens!

Thanks for sharing this!

I like to see UDL code in sources and folder=package structure for the source code.

Few ideas:

Why not save code without txt extention? Cls would go with .cls, include files with .inc and etc, like in this project, or  this project or in that one.

Would you please share a small screencast video of the general use cases which shows the key advantages and benefits?

Thank you in advance!

 

If you want a proof-of-concept or a showcase, then this link shows how the class package hierarchy is followed.

You can disable the use of .txt using two ways: 

1 - By running ##class(Port.SourceControl.Config).SetSourceExtension("")

2 - By running the wizard with ##class(Port.SourceControl.Wizard).Start() and navigating to the relevant option.

Note that this will ONLY AFFECT the appended extension, not the type itself. Example:

##class(Port.SourceControl.Config).SetSourceExtension("")  = cls/Port/SourceControl/Hooks.cls

##class(port.SourceControl.Config).SetSourceExtension("txt")  = cls/Port/SourceControl/Hooks.cls.txt

All the same for following formats: INC, INT, MAC, DFI, MVB, MVI, BAS. Except if the file is inside the web (CSP) path.

I could do a small screencast, but the usage is pretty straightforward. Anything more advanced than that is covered by the Wizard.

How to use:

1 - First time only:  import the port.xml.

2 - Run ##class(Port.SourceControl.Installer).Install().

3 - Restart the Studio.

4 - Done! Now whenever you save a file related to the project, it's structure is generated and the file is exported everytime you save it.

5 - If you want to export all items regarding the current project you can use Source Control->Export Current Project.

EDIT: Oh I forgot mentioning about tests.

Unit testing with Port:

As long as you have classes prefixed with the package "UnitTest" (which is also configurable). You can export these classes to XML and run their tests atomically.

1 - SourceControl->Export Test Suites to XML.

2 - Context SourceControl menu->Run Tests Associated with this item.

 

By default when you install Port using the installer, it sets a parameter to run unit tests as you keep compiling the classes.
You can disable that as well.

If you notice any bugs, please fill a issue.
If you still need a demonstration, please ask again.

Just like a CSP file.

You have two ways of working with that:

 

1 - If you modify the file using the Studio, that file is exported automatically when you save it.

 

2 - If you modify the file outside the Studio you can import the file again to the project and it'll be overwritten with the new version (as long as it's newer).

Anything inside the web folder is mirrored inside the csp application. Which means:

If you have a file with the path 
C:\CacheProjects\yourproject\web\css\index.css 

It's name will be resolved to:
csp/namespace/index.css

And will be mirrored like this:
C:\InterSystems\Cache\CSP\namespace\css\index.css

If you remove that file from the project, save it and export, then this file will be eliminated from the repository since it doesn't belong to the project anymore.

The same rule is applied for each type. Not only the folder "web".