My Personal Github Flow

I've created many repositories in my programming history, starting from the good old Google Code, passing through Mercurial HG and svn, ending up using on daily basis the awesome Github.
There is something I've spotted every time I've created a new repo, I needed a way to do always the same thing ... but better each time!
The very latest case is the callerOf utility, something that small and already demanding usual/common stuff such:

• a meaningful and organized structure, instead of files in the wild
• an easy way to test for browsers and often nodejs too
• a simple build process per each target, able to combine them all at speed light
• a linter for those projects that could be widely adopted and linters are so annoying ... where was I ... right ...
• thanks to the same folder structure, an already prepared .gitignore, together with the .npmignore
• a LICENSE.txt file, in my personal experiments and libraries always Mit Style
• a Makefile able to help me combining all these tasks
• last, but not least, an almost fully prepared, and basic, package.json file with main info to publish
• optionally, the usage of .travis.yaml for the awesome Travis CI service

About Travis

Today I've maden a donation to help those guys maintaining the project. The email as soon as something goes wrong is a great way to be notified about problems. I've worked in many enterprise environment where this is the default, most basic configuration, to be instantly notified and be able to fix ASAP or revert instantly and a free service working all the time doing this for all those Open Source projects cannot be ignored, and applauded from Developers indeed.
All major programming languages are supported plus it's not that difficult to configure and it's based, if node.js is supported, to the simple npm test command: awesome!
I won't tell you how much I've donated 'cause it does not matter as long as you donate something to these good fellas, right?

I Might Not Need Travis, But ...

The basic way I've configured my gitstrap, this is the silly name I've chosen for the repo with most basic structure, forces me to build and run tests before being able to push. OK, OK ... is not that if I don't build and run tests I cannot push, I mean, it could simply be the README.md edited and not necessarily code, but to know if my code/library is working, I necessarily need to make and, in that case, be sure that everything is green.
In few words, the moment I push some code I am pretty sure Travis CI will be still green but if something goes wrong with one of the node.js versions, the test, the server, whatever, really, I'll be still notified and able to react.
The classic scenario is a pull request proposed without testing, mybe looks good, only Travis will tell you if it really does, right? ... oh well, feel free to enforce whoever sble to edit even online to run tests ... if you manage :)

What I Think Is Essential

In my cases these are the most basic dependencies, able to make my workflow freaking fast and robust enough too.

• wru testing framework for node.js and web via make test, already configured in latter case inside a handy index.html eventually published via gh-pages through make pages
• polpetta, in order to be able to automate the inclusion of the same test for both web and node.js in a ctrl+click and make web shortcut
• JSHint to eventually enforce the usage of a linter, through make hint shortcut
• UglifyJS

All above projects can be simply included in the current folder via make dependencies, not distributed via npm since these are not really part of the project, except the test, where in this case a tiny overhead of 130Kb for wru testing library isn't really a problem for anyone, right? :)

This Is gitstrap

Really a sort of github boilerplate for JS related projects, something already organized and ready to go, something you can simply:

curl -s https://raw.github.com/WebReflection/gitstrap/master/new >~/gitstrap && bash ~/gitstrap && rm ~/gitstrap

Following instructions here, or if you prefer a manual installation:

git clone git://github.com/WebReflection/gitstrap.git project-name
cd project-name
rm -rf .git
make dependencies
git init
git add .
git commit -m "gitstrap in"
git remote add origin git@github.com:yourname/project-name.git
git push -u origin master

After this, don't forget to update Makefile and package.json with the right name, specially if you are planning to push to npm, as well as the README.md.
I might decide to automate this procedure too pretty soon and any extra task or contribution will be more than welcome. Right now I think this is enough.

About Files And Folders

Right, this is where I explain what the hack is that structure ... let's start from the top:

build/

This folder will contain all versions of the same projects, if the project would like to be compatible with nodejs, web or generic JS engine, AMD loader based on define logic and stuff.

Yes, A Different Automated File!

After all discussion on "how should a file be to be compatible with all the mess out there" I've realized that exporting JS is really a matter of env, so if everything else is more or less the same, why on earth pollute all possible projects with that exporting nonsense? You need AMD? You get AMD ... You need node.js? You get node.js ... and same is for generic env, is really that easy!
Please note that all builds generate a .max version of the file, those I've just linked, and a minified version too, with the exception of node.js, since I don't believe in packed server side code that much :-)

index.html

This is used to generate the test page in gh-pages, so that once the pages have been generated, the test folder will contain those tests and launched through the index.html file.

Makefile

The most important thing to edit here is the name of the project and the main file, or the list of files to use. These can be different per build, if needed, or just the same for all of them. You decide!

LICENSE.txt and other files

Have been explained already :-) Modify the name in the license, modify the license too, if necessary, and that's pretty much it. You need to edit where necessary to go with your own project.

src/

Here is where your source files should go. If the build shoul dhave different targets, as example for node or amd, I think is good to prefix or suffix them with these names. The main used as example is what the project will export, just an empty object.

template/

This might look weird but it's actually what will be used, as file, before and after each build. These files could be empty too, it does not really matter, but it's handy to have them to easily generate AMD, node.js exports, or generic closures to use before and after the generic code reused across targets.

test/

Here the big deal, where the .test.js file will be in charge of running wru against whatever test is present in the folder, as long as there is a counter part in the src too. This should make the possibility to test in isolation easier. Bear in mind node.js needs to require() but the browser can load things in pieces so both built version and other files will be included and tested, if tests are in place.

As Summary

The aim of this repo is to make at least my life easier, and you can see already in all my github repos that the structure is already like this, and every project is a partial clone of the other with tiny improvements over the Makefile and some automation maybe not necessary anymore, as it was this good old builder once in python, then in nodejs, and finally obsolete in latter repos :)
Have fun with you extra ultra cool best library ever!