Using GIT for Source Control and Community Code Contributions

Mar 28, 2013 at 1:46 PM
Wanted to start a thread following this Tweet by Marc:
@sympmarc Just did my first commit for SPServices to Codeplex using git. Gotta figure this stuff out
Personally, I think that GIT is by far the easiest tool (at least the Github implementation of it) for submitting/accepting Developer contributions to a library... With this in mind and the fact that the real power behind SPServices comes from the input of the community, hosting code with GIT is a natural choice.

So let's help Marc!

I'll Start...

Proposed Directory Structure:
  • src - Source code files
  • test - Unite test cases and/or test suite (ex. in this case, maybe webparts that test functionality). I suggest using QUnit
  • doc - Library documentation. I suggest using Markdown for the documentation... Not sure if doing this would be a duplicate effort for how it is currently maintained here on CodePlex.
  • Master - Always has the most recent STABLE code. This could be a released version or stable (well tested) code that is ready for release
  • WIP - Work in progress... Where development of new features/bugs is done.
For small projects the above should be enough... In some cases, a 3rd branch may be used for testing WIP code before it makes it to Master.

Tagging approach:

Each stable version that is "released" should be tagged with the appropriate name (ex. 2013-01). Should patches be needed prior to the next version, this tag can be used to create a branch and make the change without introducing a new major version.

Right now, I think you have SPServices as a single file project (jquery.SPServices.js)... if the project grows to have multiple files and additional files are introduced to simplify the management of the code base, then a build tool may be needed. Although I'm a long time (hold out) user of Ant, I have been wanting to make the move to Grunt (a Node.js plugin). I would suggest using that.

Version Hosting:
I suggest that you continue to host the packaged releases (version) on codeplex as you do today

As Marc mentioned in his post recently:
Remember that SPServices is open source. I rely on you, the community that uses it, to let me know what works and what doesn’t. There is just not enough time in a day for me to test everything. If I hear about problems, I try to get fixes out as soon as I can, but this is free software, folks. The best situation is one where someone runs into a problem, they devise a fix, and I get the fix to incorporate into future versions
I'm a believer of this library and although I find it hard at times to make time for contributions, without them the motivation and desire to keep these types of projects going may die out... Lets not allow that to happen.

Mar 28, 2013 at 2:06 PM

Excellent. Thanks so much for getting this rolling. Your ideas make sense.

While you were writing this, I was writing a blog post.

One of the first questions may be: Should we use git here on Codeplex (See the Source Code tab - nothing I've done there as of this writing is probably worth keeping) or move to Github? My guess is that once I actually understand git I will want to store other code-based stuff there, too. I have no idea what the differences are between the implemantation here on Codeplex and at Github are.

Mar 28, 2013 at 3:44 PM
I love the idea of utilizing git, especially on Github.

We have been using Github for building our Streamlined Studio SharePoint solutions for the past 6 months and it has become a central part of our workflow. One of those "I can't believe I ever lived without this" kind of realizations. It seems that the entire non-Microsoft world has become to depend on it for their projects as well.

I second Paul's idea on keeping the main releases available on CodePlex (especially since its become the most popular project on here :-). While utilizing Github for all future development and collaboration. Github offers great version history with comments and ownership to the line level, along with an awesome client app so all collaborators can work with the code locally. The issue tracking is a nice addon as well. Lastly, the ability to easily fork, pull, and merge code enhances the chances that collaboration will actually take place.

Marc, your library and blog have been a tremendous asset for us as we have grown our practice. So I'd love to give back to the project in any way I can. I'd love to help create/migrate any documentation (we can build it on twitter bootstrap) and even create a downloadable library with examples and code snippets to get people rolling while showing off SPServices' awesomeness. Please let me know how I can help.

Mar 28, 2013 at 4:16 PM
I'd suggest to keep it simple :).

Move source code to github and use the issue tracking and pull request cababilities.
One master branch might be all that's needed as you probably want to upload stable releases to codeplex anyway.

So for end-user there would be no change to the current situation, they go to codeplex and find downloadable releases and documentation.

Contributors on the other side would go to github.


In order to get them working effectively
  • choose some Github workflow that work best for you.
  • break down the current code into smaller, testable pieces
  • establish a build process (e.g. grunt.), ideally backed up by travis that is running tests on every build.
Mar 29, 2013 at 2:20 PM
Edited Mar 29, 2013 at 2:21 PM
I second the opinion to keep it simple. I wouldn't spend too much time thinking about branches, build or migration. You can look at the way jquery has its repo setup,, they are obviously quite experienced with this.

Create a repo on github (or codeplex) and drop the unminifed file there. You may have a structure already in place, something like this isn't uncommon:
Don't name the files with version information in them, that is what the source control system is for. You use branches and tags for versions, but again, don't spend too much time thinking about this ahead of time, you cross that bridge when you get there. If you look at jquery's repo and expand branch dropdown, you can get a sense of how they are utilizing it.

I know codeplex supports git, I haven't used it. I have used github for source control and codeplex for documentation. On my github page I only say to go to codplex for docs. I am not sure how I feel about it, this was dictated mainly by the fact that the sharepoint crowd tends to be more likely to look on codeplex then on github. That may not be true anymore though. You have a much bigger fish to fry with your project and you have a much better sense of the user base and their preferences.

Hope that helps.
Mar 29, 2013 at 2:30 PM
So the things I'm getting from all your posts are:
  • Git is good
  • Simple is good (I love KISS)
  • Github is better than Git at Codeplex (maybe?)
  • You're all going to be helping much more with SPServices
OK, that last one might be wishful thinking.

Here is the doc which explains using Git at Codeplex.

I've downloaded both Github for Windows and Git for Windows. Any preferences? I don't see why anyone in the 2010s would want to run command line anything. I'm more of a GUI guy.

I'm off to Github to see what I can figure out.

Mar 29, 2013 at 3:10 PM
Github for windows: written by github the company, more specifically Phil Haacked
Mar 29, 2013 at 3:17 PM
I'm happy to see interest from others on contributing to this library and helping Marc alone keeping up with maintenance on SPServices. Sounds like we are really going to see FOSS at work here... :)

Re: Codeplex -vs- Github
My opinion here will be bias... I started using Github less than 1 year ago and am really liking it - mainly (as @marktiderman mentioned above) because the workflow there is very good... note that it has nothing to do with GIT itself, but rather the workfow that github has built around git itself. That being said, I am opened to using GIT here in codeplex... (does anyone know if mentions of issue items in commits automatically update the issue itself?)...

I also agree with @Rainer and @tstojecki on KISS... As the size/functionality grows, simplicity will need to be maintained with the help of scripts/build tools (take a look at the jQuery grunt file). Example, most of my build scripts do at a minimum the following:
  • Generate developer jsDocs (javadoc type of stuff)
  • Generate user documentation (I used to do it with NaturalDocs, I now use Markdown)...
  • Create minified version of library file(s)
  • Create a distribution package (zip file with source, documentation and minified versions)
All of this is scripted and easy to do/have... it saves a ton of time...

And lastly... @sympmarc : I would not dismiss your statement above "You're all going to be helping much more with SPServices" - That was my intent on initiating this threat... its a calling to the community to participate and contribute... in my opinion, given the quick responses received thus far, I say we may be up to a good start. At some point, you may really want to put this to the test by drafting a plan (I can help) and come up with a list of tasks that should be done in order to setup all of this... let's highlight the areas we (the community) can help with and see how many answer the calling...

One last word on my personal usage of git... I do, from time to time, use it from the command line, but have found that most of the common tasks are done just fine using a GUI (I use aptana for eclipse, which includes a GUI for it, as well as a command line shell).

Mar 29, 2013 at 8:20 PM
I don't have any input on the github v. codeplex git implementation...although I'm interested in the outcome.

As far as documentation, I'd recommend using Sphinx found here:

It would provide the ability to ship the documentation in a variety of formats in the zip file and host the same single-source documentation on GitHub (and codeplex?).
Also separates the documentation from the code, which in this situation is how Marc already had the docs structured and would allow contributions from people to the documentation separate from the code.

My $0.02...thanks,

Apr 6, 2013 at 10:55 PM
Thanks for all of the input. I'm not sure where I'll go with things, but I would like to learn to use github. Josh McCarty gave me a very helpful tour yesterday and I'm getting there.

Nov 30, 2014 at 8:39 PM

I'm finally really doing this. I've just put up a blog post if you want to jump back into the discussion.

Blog Post: SPServices and Github – This Time I Mean It