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
LICENSE.txtfile, in my personal experiments and libraries always Mit Style
Makefileable to help me combining all these tasks
- last, but not least, an almost fully prepared, and basic,
package.jsonfile with main info to publish
- optionally, the usage of
.travis.yamlfor the awesome Travis CI service
About TravisToday 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 testcommand: 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.mdedited and not necessarily code, but to know if my code/library is working, I necessarily need to
makeand, 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 EssentialIn 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.htmleventually published via
- polpetta, in order to be able to automate the inclusion of the same test for both web and node.js in a
- JSHint to eventually enforce the usage of a linter, through
make dependencies, not distributed via
npmsince 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 gitstrapReally 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 ~/gitstrapFollowing 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 firstname.lastname@example.org:yourname/project-name.git git push -u origin masterAfter this, don't forget to update
package.jsonwith the right name, specially if you are planning to push to npm, as well as the
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 FoldersRight, 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.htmlThis 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
MakefileThe 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 filesHave 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
mainused 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.jsfile 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 SummaryThe 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
Makefileand 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!