This is an age old
question and debate. There are pros
and cons to both sides of the argument. In this post, I’ll explain my experience
committing generated (built) files to master for my libraries and why/how I
don’t do that anymore.
First, generated files?
In the context of a library, the generated files would be what the user of your
library includes on their page with something like a script tag. So the
concatenated, compiled, and minified version of your library files. For small
libraries this may not be needed, but for multiple-file libraries that need to
run in the browser of today which doesn’t support ES6 modules yet, you’re going
to want to distribute a single file. This is what I mean when I say “generated
files.”
So, why do it?
You might be tempted to commit built files to source for a few reasons:
- Bower needs them there
(stop using bower) - Makes it easier for people just downloading the files (not using npm or
bower) - Enables use of rawgit for examples in tools like
jsbin or plunker
For a long time, these are the reasons that I committed my generated files for
my libraries to my git repository. Everything worked out great! But I did have a
few problems.
Problems…
These are some of the things that I just dealt with because I hadn’t thought of
a way to get those benefits without these issues. Until now.
Exploding git changes
Looks like a huge boost of features right? Nope! that bump is when a build was
added to ng-stats (there were a few other significant changes as well). The
subsequent bumps are whenever a new version was released (and hence the build
re-run and re-committed). This make’s it difficult to get a good read of the
activity of a project.
Terrible Git Diffs
When developing the library, you have to make sure that you only commit the
built files when doing a release (and not with other file changes), otherwise
your git diffs are going to be a huge mess and it’ll be hard to identify when
and what changes entered in the codebase.
But even having this separation is frustrating at best because diffing two
commits that are separated by a build will result in an impossible git diff as
well. 😫
Contributions to dist
If you’re writing an open source library, chances are you want to make it easy
to contribute to and
welcoming to new contributors.
I have often received
pullrequests
that make changes to the generated files rather than the source files (or commit
a run of the build script). Their contributions would be overwritten next time
the build is run! Others will submit
a
PR that includes the updated
dist (which ruins the diff for that commit as mentioned earlier).
For these kinds of contributions, I always have to (kindly) ask the contributor
to resubmit the PR with a force push so that commit doesn’t get into my history.
This is not a very good experience for contributors 😿
If you want people to contribute to your library, you want to make it as
straightforward as possible. In my experience, this is more easily accomplished
when not committing the generated files.
My Solution
NOTE: This is no longer how I do things. I just rely on
unpkg
So, how do we get the things we like about committing the generated files
without these drawbacks? It’s simple, only push the generated files to a special
branch for releases. I call this branch “latest” and I’ve automated this
with the package
publish-latest.
Basically, you run your build, then run publish-latest which runs
this scriptwhich
will commit your built files and push them to your latest branch automatically.
You can totally do this locally, but it actually works best when done with
semantic-release and
TravisCI (or some other CI service).
How do we still get the benefits?
- Bower -> tag the commit that publish-release makes (semantic-release does
this for you) - Downloading -> Look at the latest branch
- rawgit -> Point to the latest branch
How does this solve the problems?
- Exploding git changes -> Just ignore latest, focus on master (that’s what
github’s contributing graph does as well). - Terrible git diffs -> You never need a git diff on the latest branch. It’s
just as generated (useless to git) as the code. - Contributions to dist -> Most people won’t checkout the latest branch to
contribute. I’ve never had that problem.
For an example of this actually working, you can see
several
of my
projectsand
other’s that
have already been moved over to this (including
publish-latest
itself).
Conclusion
There are a lot of tools to help you with the development of your open source
libraries. If you’re interested, I have a series on egghead.io that takes you
from the very beginning to building out a great library. I recommend you give it
a look:
How to Write an Open Source JavaScript Library.
FAQ
- Does this work with CDNJS? It appears to work just fine with
angular-formly - What about storing the latest branch in an entirely different repository? This
is actually not a bad idea, and with the url flag of publish-latest, you
can totally do this.
Source link
