Balance of Modularity and Packaging

the-problem.md

So I have this question I asked on twitter and irc. I got some useful feedback, but thought putting the question clearly in a gist would lessen the confusion.

The Problem

As many of you know, I'm working on js-git right now. I've come across a question about how to package the various modules that make up the library and am unsure which is the best path.

The modules in question are things like:

• pkt-line - A min-stream codec for deframing and framing git protocol data over TCP
• list-pack - A min-stream codec for consuming a stream of git PACKfile data and emitting raw objects
• fetch-pack - A high-level min-stream codec for speaking the fetch-pack protocol. Depends on list-pack, pkt-line, and others.
• inflate - A min-stream codec for inflating the deflated bits inside PACKfile, dependes on list-pack
• apply-delta - Apply git deltas used only within the git PACKfile format.
• etc...

Modules that I've already broken out of js-git and made into standalone packages/projects are:

• min-stream - A collection of min-stream helpers to make using min-stream codecs easier.
• min-stream-node - Adapter for node.js exposing streams as min-stream compatible.
• min-stream-chrome - Same as min-stream-node, but for chrome packaged apps using chrome.* APIs
• http-codec - A min-stream codec for converting between TCP and HTTP protocols (lets you implement HTTP clients and servers)

I've also broken out the sample applications that use js-git into their own repos.

• js-git-node - A CLI tool for working with git repos (replaces the git command)
• js-git-app - A chrome packaged app that allows working with git on chromebooks.

As you can see I'm already taking anything generic out into it's own module.

My question is which is better for the js-git community?

Solution A

Keep all the git-specific code in a single js-git repository as a single meta-package. This is how bops, min-stream, and continuable are all packaged and it works well for them. The individual modules within the package can still be used independently of the rest. If you're unable to use just part of a package that's an issue with your tooling, not my package.

This does mean that some of Chris Dickinson's code will need to be assimilated into the main js-git repo. It's currently scattered across his various repos (mostly starting with git-*)

Solution B

Use many small individual repos. Each with it's own independent owner, repo, CI integration, package, npm name, version, issues, etc. Each module will have it's own code style and act like an independent project.

This also has many benefits, but makes combining everything quite the hassle.

One interesting constraint of the targets that js-git supports is I really want to be able to develop js-git on a chromebook without going into dev mode (which has nasty security implications and a really ugly warning at every boot). As stated in my kickstarter, I want to help kids get into programming easier. The less barriers the better. Chromebooks are the #1 selling laptop on Amazon and have been so pretty much since they came out. Most of these are bought as gifts to kids. They often can't put their device in dev-mode and install linux, but they can run chrome apps. In this environment, there is no node.js, no npm, no browserify, and no git. I'm fixing the problem with no-git, but I can't depend on node, bash, or any normal command-line tools for packaging.

Tell me what you think.

I'm especially interested in hearing from my backers to hear what they expect.

Keep in mind that with both proposals, the modules themselves will be standalone code with independent tests. With either route, there will be a pre-packaged version for people who just want to use js-git. The question is about what contributors want. Do we want independent issue trackers, CI integration hooks, packages, or do you see js-git as a single project with many modules that make it up?

The stuff that's not git specific will already be pulled out into independent projects, so that's not in question.

@st-luke

It's more important to do what's right than what makes the node community happy.

This is all about doing what's right and facilitate ease of reuse and community contributions. If that makes people happy as well that is just an added benefit ;).

@thlorenz I'm referring about doing what makes it easier for people without a command line to use this, not what makes it easier for already capable programmers.

I think I'll go for option B for now. It seems the negative parts will be temporary as better tooling is written for the other environments. I really don't want to duplicate efforts by maintaining a fork of Chris's code.

It should be noted that

independent issue trackers,

Can be solved with a single meta github repo to centralize issues. I would imagine you want fine grained issues on individual bugs and higher level issues on js-git itself

B

Hello from 2017! Would anyone from the original project care to write a retrospective? I myself have found the result to be incredibly frustrating. As an outsider trying to comprehend the project & how to use it, what I've experienced is dozens upon dozens of modules (Tim has 68 results for source repositories matching "git" and Chris has 32 results for source repositories matching "git"), with varying degrees of documentation, and no website explaining how each module relates to each other. I've literally been using a hyper-media driven approach, looking at each module on npmjs.org and following the "Dependencies" and "Dependents" links. I think the root node for @creationix is js-git and the root node for @chrisdickinson is git-fs-repo but those are just best guesses.