tsquillario/Jamstash

Utilize GitHub's release functionality (and simplify dist folder management)

Closed this issue · 1 comments

pR0Ps commented

Generally, including build artifacts for every commit is frowned upon. Having the dist folder always be completely blown away and rewritten on every commit makes resolving merge conflicts between branches and rebasing much more difficult, as well as bloating the size of the repository. To help with this, the project could make use of GitHub's releases functionality.

Proposal 1 below is closer to the current process, while proposal 2 is a more radical change. Personally, I feel that proposal 2 is better from both a dev and user perspective, but both would be an improvement on the current system.

Results from adopting either proposal

  • [+] Provides the dist folder via releases
  • [+] Easier development due to dist folder mostly being ignored except for releases (less merge conflicts, easier rebasing, etc)
  • [+] Creates releases that non-devs can easily download and deploy without needing the entire node+npm+bower toolchain
  • [+] Allows people to subscribe to release notifications (via an rss feed or other services)
  • [+] Changelog will be easily viewable in releases
  • [-] To use a specific commit, it will have to be manually built (think git bisect or non-devs wanting to use a specific branch with an unreleased fix in it)

Proposal 1 - Only update the dist folder on version bumps:

  • For normal commits, just ignore everything in the dist folder and only commit source changes
  • To push a release, bump the version, add text to the changelog, run build, add the entire dist folder, commit everything (with a message like "Bump version to v1.2.3"), and run git tag v1.2.3.
  • Doing something like git push origin master --tags will then push that commit and the tag to GitHub, where a new release will automatically be created.
  • [optional] On the tags section of the repo, find the pushed tag, click "add release notes", and add a changelog for the release (copy from app/common/json_changelog.json) to the description.
  • The release will provide an easy download button to grab the repo at that tag, which will include the dist folder.
  • The rest of the commits won't include changes to the dist folder so won't have issues with merging.

Results (relative to proposal 2):

  • [+] Provides the dist via clone and releases (flexibility I guess?)
  • [-] Still includes the dist folder in the repo with all the problems that entails.
  • [-] Releases also contain the source in them with the dist folder as a subfolder (typically you would only want the dist for a deployment - not the source).
  • [-] During development, git status will show loads of files changed in the dist/ folder that you have to remember to ignore (and teach new contributors to do the same).

Proposal 2 - Totally remove dist from the repo and provide it via the release functionality instead:

  • Remove the "dist" folder from the repo by adding /dist to the gitignore.
  • [optional] Rewrite history to remove it from history. This would massively reduce the time and bandwidth the initial git clone takes. However, because it would be rewriting history, other people's forks would no longer be based on the latest commit.
  • To prepare a release, bump the version, add text to the changelog, run build, commit (still ignoring the dist folder), git tag, git push --tags. This will automatically create a new release.
  • On the tags section of the repo, find the pushed tag, click "add release notes", Add the changelog for the release (copy from app/common/json_changelog.json) to the description, zip up the current dist folder and add it to the release as a binary.

Results (relative to proposal 1):

  • [+] Releases only contain the built files - ideal for easy deployment
  • [+] No dealing with diffs in the dist folder during development
  • [+] Smaller repo size going forward due to the lack of the dist folder changing per-release
  • [-] Slightly longer process for releases (automation to the rescue?)

Resources:

  • The ability to create releases via the GitHub API exists: https://developer.github.com/v3/repos/releases/#create-a-release . Could be integrated into the existing grunt script.
  • I'm sure some sort of automated thing (TravisCI maybe?) already exists to do this style of artifact release but don't know specifics offhand.
pR0Ps commented

Fixed by #255