9

I have a web application, including front and backend code, which I would like to push to github, but, it currently has some of its dependencies managed it its source tree. The backend code is Perl, and installing module dependencies from CPAN is well understood, so I don't have those in there. I mostly have jQuery libraries and some other Javascript libraries that are open source.

-mycode
-mydir
   -mycode
   -jquerylibs (with their license)
   -mycode
   -jslibs     (with their own licenses)
-mycode

For deployment, this is extremely convenient, as I can control which versions of the libraries are being used, and also not force people to use a CDN (Content Delivery Network) to load jQuery etc. from a remote domain which might not still be online in three or five years.

However, I am not sure if it is appropriate to include the source of other projects in with my application, even if I include the license files.

What's the best way to include dependencies like this in an open source web application, doing honor to the dependencies whilst maintaining the convenience of a working deployment?

2
  • 1
    If you want to tackle this, Git submodules would seem to be the way to go, but in reality, I wouldn't worry about it too much, and run with the setup you've got.
    – Matt
    Commented Mar 19, 2013 at 13:05
  • thanks... git submodules sound exactly like svn:externals, which I do use in some projects, when the possibility of committing back upstream to those other projects exists. But I think in this case, I only want to rely on tagged versions, and not point to external repositories.
    – Marcus
    Commented Mar 19, 2013 at 13:18

5 Answers 5

1

Have you considered using a package management like Bower for your JS dependencies? Package management for this front-end stuff is becoming more popular and similar to backend modules (CPAN, gems, pip, etc.)

0

Nothing is going to be around forever - the question I think you're trying to answer here is how to set things up so that the sources of truth will last out the lifetime of the code that depends on them.

Including the source in your tree is perfectly reasonable if it's just a couple things and you're dependent on a specific release.

As an alternative, since you're pushing to GitHub anyway, perhaps you can fork the necessary prerequisites, tag them appropriately for your application, and then include them as Git submodules. That way, they will be around at least as long as the canonical source of truth for the main application's source code.

If they're not on GitHub now, but are open source, it's still reasonable to add them to GitHub yourself and then add these new GitHub repos to your project as submodules.

0

Including the source in your project is fine, as long as you obey the license(s). It could be distracting though. Somebody not familiar with jQuery or whatever else might not realize that it's third party code. They might waste time digging into it or something, not realizing that it's unrelated to your project.

Regardless you should document the dependencies in a readme file (e.g., README, INSTALL, DEPENDS, whatever). It could be that you currently use jQuery x.y.z, but there may be bugs in it that affect your software. So you can't guarantee that fixed releases will always be ideal.

Usually instead of bundling the source (since it will be unchanging and pretty much doesn't need to be tracked), I instead write a helper bash or Perl program to fetch the dependencies from the net. That way, there's an easy button that will probably work for people that don't want to do a lot of reading or manual work, but you don't have the clutter of other projects distracting people from your own code, and the dependencies aren't needlessly tracked by your repositories.

Append:

If possible, you should also prefer to completely separate third party software from your own in the tree so it's clear where third party software begins and where yours is (again, just so people don't mistake it for yours, which could lead to nonsensical requests of you, etc.).

* <root>/
`-* README
`-* extlib/  <-- third party stuff can be tucked away in here, for example
| `-* <third_party_code>
| `-* jquery-x.y.z/
| | `-* ...
| `-* other-x.y.z/
|   `-* ...
`-* include/
`-* Makefile
`-* src/
  `-* <your_code>
  `-* main.c
  `-* ...

If it needs to co-mingle at deployment then have the build system copy or link things into the appropriate places.

0

I'd also make sure of the type of licence you require for the app. There are a few out there fore the purpose of open source that can let the downloader alter or even change the type of licence and use for it. There of course is variations of GPL licences or even MIT licences. Look for the one that suits your needs.

0

I think there is no simple "best" solution for your requirement. I did use many different approaches in various projects. All of them did work out quite well - the thing that counts is how you prefer to organize the code, so you can easily maintain it over a longer period. This of course is a rather personal thing.

I myself like to use CDN for jQuery - it has way more advantages than the (very unlikely) risk, that google-CDN Server is down for longer than 5 seconds. And even then you can build a fail-save into your Code to load your localy hosted jQuery framework in case CDN is not reachable, like this:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script>window.jQuery || document.write('<script src="js/lib/jquery-1.10.2.min.js"></script>')</script>

About the code organization: I prefer to manage my files in the following structure

/app
  +- /js
  |   +- /src               <- my custom scripts go into "/js/src"
  |   |    +- general-ui.js <- I create/edit this file
  |   |                        Usually I only edit files in this directory
  |   +- general-ui.min.js  <- the minified version is automatically stored in "/js"
  |   |                        I never edit a file in here
  |   +- /lib               <- external libraries go in here.
  |       |                    NEVER edit a file inside the "/js/lib" folder!
  |       +- jquery-1.10.2.min.js   <- Always add version-number to the files in /js/lib
  +- /css
  |   +- /scss              <- my SCSS source files which compile into "/css/style.css"
  |   +- /lib               <- stuff like twitter bootstrap css. Never edit files in here
  |   +- /font              <- webfonts used by the css
  +- /inc                   <- my own PHP classes/modules/etc
  |   +- /lib               <- external PHP modules (again: never edit these files yourself)
  +- /img                   <- all images used by the application
  +- /web                   <- my own PHP/HTML files
  +- index.php              <- this will load the /inc/application.php class which handles the rest
  +- debug.php              <- same as index, but enables some debugging flags enabled
  +- config.php             <- config stuff (DB, etc)

In my approach I will always include all external files in the application snapshot (e.g. including the version numbers of jquery and other libraries) - because after all the application is built for, tested with and dependent on a certain external library; So I want to "hard-link" this libraries to the code as they form a single unit.

So my advice is to not to use git submodules but rather have a single repository that includes all files, which you are completely in control of. But use CDN to load libraries (you can control exactly which version to load, which makes this solution perfectly fine). A new version of jQuery? First implement is locally, test it, and then add the new jQuery file to the /js/lib folder (do not overwrite the old one but add a new file with unique version number)

Not the answer you're looking for? Browse other questions tagged or ask your own question.