NiC is now available for collaboration on github! What have I learned in the process? Help is essential, first of all. And probably last of all. Otherwise, I did learn a few important things about the github workflow, which was very confusing to me. For those of you who, like me, are new to the tool and are mostly humanities-type people, I hope this clarifies things a bit. It’s very helpful to learn a bit about how others set up their workflow, because things can get very confusing, very fast, once you start making changes to the app, and with collaborators, it’s just ridiculous to assume you don’t need to think about this. You’ll see what I mean if you try to go forth, willy-nilly.
For starters, a little about my setup. I have oXygen and eXide (through the eXist-DB) installed on my computer, and I work in them both–I should really make a decision about what to use, when, because things can get a little tricky if you don’t refresh while moving from one to the other. I also set up oXygen to work with eXist-DB–here’s a how-to from eXist, and here’s some documentation on native XML database support from oXygen.
I have github running through the GUI on my Windows machine. (I tried, I really did, to use the command line, and it stumped me. Hey, I’m picking my battles!) In eXide, I set up the app to synchronize automatically to the local repository folder, which I’ve called NiC and located inside Documents/Github. You can set this from eXide in Application/Synchronize.
Now that that’s clear… Basically, I have a process that’s derived from this forum post from @wolfgangm (HT @joewiz):
My workflow usually is: I create a new app in eXide, do some first edits and synchronize the entire app to a directory, which I then put into git. I continue to develop inside the db and synchronize again when I think it’s time for another commit. The advantage is that I can easily delete my app from the db when I messed it up and re-import the xar from the directory on disk (calling “ant” inside the directory will generate a .xar which can be uploaded again via the dashboard).
Now, some of that is Greek to me, but I also learned from @joewiz that oXygen has its own install of “ant” locally, so there’s no need for the command line. Unless you’re really hardcore about it. Or unless you know stuff that we regular folk don’t. More about “ant” later. This is just to show that hearing about other people’s workflow is useful before you really get into things.
Once I got to a place where I needed more collaboration, I downloaded the application from inside eXide (Application/Download app), which gave me an .xar file. (This is basically like a .zip file, and in fact you can just rename it from .xar to .zip to see what’s inside. You load new packages into your dashboard by adding .xar files, so this is an important bit of information.) Then, I renamed it .zip, uncompressed it, and copied all that stuff into Github/NiC. You could uncompress into that folder, too, but I wasn’t that savvy.
Now, I need to get all this stuff into the public repository. So, I went to the github GUI on my local machine, made a new repository, pointed at the local folder I just uncompressed that .xar/.zip file into. Once that’s done, you can make your first commit–in my case, I called this “Added xar contents.” You can see that (basically first commit–the earlier one is set up automatically [I think] when you create a new repository) here:
So, your stuff’s up there for folks to see and make edits to. You can choose to incorporate these edits (commits) or not as you work on your project and push those edits to the cloud through the github GUI by using the handy check boxes that will appear. (I’ll try to remember to put a picture of that here, too.)
Remember: you’ve now got two copies on your local machine, and one copy that is sort of like “swing space” between your machine and the cloud–that’s what’s on github. This means you’ve got three pens/paddocks/corrals for your app, and now you can juggle. Sorry for the mixed metaphors there, but you get my point. Here’s an image of the workflow I’m using:
I just made this up, but I think it shows what I’m doing. Normally, the flow between A. and B. is pretty seamless, but the app may need to be reinstalled when you’rve accepted edits to configuration or controller files. To do this (and note, this will work for any app if you have it in .xar form–pretty cool, huh?), open build.xml from the local github synch folder in oXygen, and run the transform scenario; this calls oXygen’s copy of apache ant, which is “a Java library and command-line tool whose mission is to drive processes described in build files as targets and extension points dependent upon each other. The main known usage of Ant is the build of Java applications.” Basically, it’s a compiler, I think. When you run that from oXygen, you’ll be left with a tidy new .xar file in your github synch folder, which you can then add via the eXist package manager. Neat, huh?
I did all this and re-opened the NiC app–and look, the edits made to the controller.xql and app.xql files for search functionality have taken effect! I now have basic search functionality within the titles, heads, and paragraphs in my xml files.
It would be weird if this worked fully, though–clicking on the title produces an error, because apparently the app is calling part of the outline function, which I deleted as there is no need for an outline with these short .xml files.
This just gives me a new problem to solve. Onward!
Tonya Howe 