Sublime Forum

Workflow for Plugin Development, Package Control, and Github

#1

So, thought I’d check in with folks on best practices on workflow here. So I have my language mode plugin that’s doing fairly well I think. I ran into an initial problem with naming however (path names for settings, snippets, python modules). Now that I’ve got this all committed and synced with GitHub and PackageControl, I’m running into trickier issues.

My original folder name was vhdl_mode. When I committed to GitHub I called it VHDL Mode. This is probably actually the most correct name, and this is how it displays on Package Control as well. Now when that package is downloaded it’s named VHDL Mode.sublime-package. However I have been using GitKraken for local repository control. When it cloned the GitHub project, it named it VHDL-Mode.

Presumably if I take the sublime-package file and extract it to %appdata%\Sublime Text 3\Packages as VHDL Mode this is effectively identical to the zipped package file. That would give me a testbed to work on. I suppose I can keep my repository separate from the test zone, that way I’m not inflicting changes on myself while editing. The entire point is to create a testbench area that can be used, but then also have as close to the user environment as possible so that I know I’m testing what they will see.

Is there a way to make PackageControl download and unzip into a zone on a package by package basis? For the ones I’m not working on, I’m happy to have them in their compressed state, however for the one that I am the author for, it’d be nice if that one was extracted into an uncompressed working fashion.

Does anyone have another way of handling development, test, and delivery combining GitHub, and Package Control on their local setup?

EDIT: So yeah, the extraction of the sublime-package and putting it into a directory of the same name under Packages didn’t work out correctly. A ton of errors from sublime_plugin.py about names. Now trying to come up with another solution.

0 Likes
#2

I can tell you about my workflow. I just clone the package on the User Packages folder. Do everything I need from there. I do not have my own packages available on package control installed by package control, as I have them cloned as git repository. I just handle everything with git on the Packages folder.

But I have another Sublime Text portable install, I run where my package is installed from package control, so in one life time, I opened it to see how it is behaving as being installed from package control, and it was fine when I checked, after a minor/major version release.

2 Likes
#3

My workflow on OverrideAudit was/is something like the following:

First, I created the folder Packages\OverrideAudit, set up a git repository in it, and shared it on github in a repository with the same name. All core development happens within this single checked out copy on my Linux machine, although I did also have a checked out copy on one of my Windows machines and a MacBook so that I could periodically verify that everything was still working as expected on other platforms.

When it came time to release to Package Control, I released it under the same name as the repository to ensure that it would have the same name “in the wild” as it does locally on my machine, and removed the local directories from all machines except my primary development machine.

Once it was officially in Package Control, I modified my Package Control.sublime-settings configuration file to include OverrideAudit in installed_packages and also in ignore_vcs_packages (this configuration file syncs across all of my Sublime installs on all machines).

So now all machines automatically install the package and keep it up to date, and if I’m doing any hard core development on one of them I can manually check out the repository and Package Control will leave it alone.

For the most part it’s easier to do development on just the one machine. Prior to a release I create overrides for all of the files modified during the last batch of changes and place them on a Windows machine and the MacBook to override their installed versions, just to double check that I haven’t broken anything. (for a meta win, OverrideAudit come in handy for testing overrides of itself :wink: ).

In all cases I try to keep all development (even locally) in a useable state. So if I’m working on something complicated that can’t be finished and primarily tested in a day, I throw it into a branch and then switch back to master locally at the end of my development day to keep my local version working.

As @addons_zz mentioned, I also have a couple of sandboxes with portable installs that I can use to double check that the behaviour I’m seeing is the same as what the user would see. In my case I have one for the latest stable release, the latest development release and one for the build that I set up as the minimum allowable version to support, so that I can cross check that I haven’t made any API blunders.

Potential ways to test this way include cloning/copying the raw files to an unpacked package directory of the same name or (I think better), using Package Control: Create Package File to create a sublime-package that you manually put into the sandbox Installed Packages folder.

The latter is most important if you do anything accessing package resources at all, as it will be sure to let you know if you’ve made any incorrect assumptions about files being present that are not if you’re installed as a sublime-package file.

7 Likes
#4

This is more of a Git question, but like I said, I used GitKraken to handle local VC for the repository. It’s in a particular directory. Is there any reason why the repository couldn’t be the directory in Packages? I don’t know if it’s required that the root be named VHDL-Mode because GitKraken chose to replace the space with a dash (rather than an underscore or a blank line).

EDIT: Actually I think that was my fault. The repository on GitHub has the dash in the name. Perhaps I can rename the repository to match how it would be done in Packages, though now that would need a new modification on the Package Control channel, so maybe it’s not worth it for this one now. I am usually pretty choosy about token names (projects, files, blocks, variables) but this time I seem to have made poor choices. Oh well, live and learn.

0 Likes
#5

Yes, you can rename your repo in GitHub pretty easy. I name repos for Sublime Text like they are a Python module, so no spaces, and I use underscores if I need to. This is so I can check them out directly without a name change, though you can checkout to a folder with a different name than the repo pretty easy with GitKraken (if I remember correctly). GitKraken occasionally goes wild and eats up too many CPU cycles. I want to use it more, but it annoys me everytime it starts gobbling up too much CPU cycles.

3 Likes
#6

I really only have it open when I am going to do some repository work and otherwise leave it unopened (much the same as my workflow for Jazz/RTC for where I work.)

Well I’ll investigate what might need to happen on the Package Control repository then if I rename the package repository something slightly more clone-friendly. That’s a pretty official channel though, so I’ll really only do that as a last resort. It might be a better solution this time around just to try to fiddle with the VC program locally.

EDIT: This is a good solution. I was able to just clone the repository as named, into a friendly ST Packages folder. I’ll just have to be very cognizant of path names should I use the. I think most of the feature set where I might have used it are already finished, so shouldn’t be a very big issue.

0 Likes
#7

I usually make a mess of this, but seem to have it under control these days… It’s important to have the same name on disk as in package control, but you can always move and rename the folder after cloning. So that’s what I do now. No experience with Gitkraken, but git itself doesn’t care what the folder is called. So, I have my packages cloned into Packages, folders renamed if necessary although I tend to take the no-spaces, CamelCase approach because it always works everywhere. If I ever mess up a branch, switching it back to master is usually all it takes to make Sublime usable again.

2 Likes
#8

Yes, I usually do camel case as well, but I was mainly trying to illustrate treating the the folder naming as a module.

Yes, you can always just check out via command line to your specific folder. Git really doesn’t care at all what you checkout to.

Working off a branch for features and bugs is always good good practice, but though I am trying to do better at that, and I know better, anyone who follows my repos will know I still push to master :smirk:…

0 Likes
#9

It’s definitely easy to make a hash of version control, especially the first time around. In my case I was trying to maintain the same name as the Emacs mode, and in emacs everything-is-chained-together-with-dashes. Also, the language name is an acronym with all caps so that adds its own issue with CamelCase.

Fortunately I think I can keep one machine as development primarily and then check out the “user experience” on another machine, make sure things work the way I expected them to.

1 Like
#10

I admit I may have to reset master once or twice for this to work :wink:

0 Likes
#11

My git workflow:
https://blog.june07.com/development-workflow-sublimetext-plugin/

I basically setup my git working directory under the “Pristine Packages” subdirectory as "Pristine Packages/<MY_WORKING_PACKAGE_DIR_NAME> and use a small script to continuously add a symlink to the Sublime Packages directory which works nicely to cause Sublime to notice the changes.

I came to this thread while hitting my own head during writing my own Sublime plugin for the first time. Hopefully the info helps some others.

0 Likes
#12

This is a most useful thread (even if old), and I hope people will keep adding their tips here.

I just wanted to drop a quick tip regarding cloning the repository with a different name in the packages folder. Don’t forget that you don’t need to clone and rename, since Git allows to clone directly with a custom name:

git clone <RepoURL> <DestinationDirectory>

I was hoping to use symlinks in the packages/ folder, so that I could have ST3 read the package from another folder elsewhere, as if it was inside the packages/ folder. But, from what I’ve read so far in the forum, it seems that this doesn’t work too well under Windows OS, due to limitation on how the OS handles folder update notifications via symlinks.

So, for now, I’m sticking to the advise found here — i.e. work locally directly in the Git repository inside packages/ folder, and set Package Control to ignore that folder as being version controlled.

Does anyone know if using symlinks inside the packages/ folder is achievable under Windows? i.e. with ST3 receiving all update notifications correctly. Or is it an OS limitation which can’t be worked around?

0 Likes
#13

I think this was officially fixed in Dev Build 3158 and released in Sublime 3.1 (build 3170); if you check the changelogs, there’s this entry for that build:

  • File system notifications on Linux and Windows now account for symlinks (and Windows junctions)

With the caveat that I don’t do a ton of Sublime development on Windows, symlinks on Windows seem to work fine for me; I prefer to keep all of my code projects in one place so I symlink packages to the appropriate location and I don’t recall any issues with this in recent memory.

As an example, on this Windows 10 machine in a cmd window opened as administrator:

mklink /d "c:\Users\micro\AppData\Roaming\Sublime Text 3\Packages\TestPackage" d:\Projects\TestPackage\
symbolic link created for c:\Users\micro\AppData\Roaming\Sublime Text 3\Packages\TestPackage <<===>> d:\Projects\TestPackage\

The structure of the source of the link is:

D:\Projects\TestPackage
λ tree /f
Folder PATH listing for volume DATA
Volume serial number is 82C4-1F05
D:.
│   sample.py
│
└───syntax
        SampleSyntax.sublime-syntax

If I open the plugin or the syntax and save the files, the console generates the expected messages regarding the reload, which is true whether I open the files from the source of the link or from the packages folder.

I don’t tend to have a lot of nested folders in my packages, so perhaps there is some edge case in that regard, but I’ve never encountered anything like that myself.

1 Like