Add a page for design decisions and reasoning

[smellsblue]

There should be a page to describe various design decisions with a short background of what the decision was aiming for. Please add to this issue any decisions or questions that we can include.

[smellsblue]

• Why are yanked upstream gems still downloadable from Gemstash? If you are using Gemstash, the dependencies you are bundling against might start to get yanked, but you may not be ready to deal with upgrading or changing your dependencies, so keeping the gems you've bundled in a safe place helps avoid the need to do an emergency upgrade due to a gem being yanked. The various dependency APIs will still report the version as yanked, but a bundle against a lockfile will still succeed.

[pcarranza]

• Supporting ruby by caching gems locally so rubygems does not need so much bandwidth and/or scaling.
• Storage has a trie structure because some filesystems do not support more than 32k files as childs of a node (folder) (I'm looking at you ext3), this is not a common situation, but since bundler philosophy is to support old things like ruby 1.8.7, it makes sense to support this.
• Storage also will normalize chars in gem names and in upstream uris to support some filesystems, but particularly it will add a hash of the gem name to prevent having collisions at the gem name only in casing (there is at least one case of that) in case insensitive filesystems (like default hfs).

[pcarranza]

Is this a candidate for the wiki? Does it make sense to build a github page for this kind of things? (Blog like)

[smellsblue]

I think it could be another markdown doc. I had asked about docs via wiki and there was some strong pushback. Github pages might work, but it would be nice if all docs were in 1 place, so if we did that, I'd want to consider moving the rest of the docs to github pages too.

[pcarranza]

Aaah, cool.

Maybe building the page with the markdown docs?

[smellsblue]

You mean building the github pages with the markdown docs? That would be cool, as long as you could continue to browse them directly from the repo like you can now

[pcarranza]

Exactly that. Just a thought although.

[olleolleolle]

Example filenames that could go in a website or wiki folder:

• website/design.md
• web/meta/design-decisions.md
• website/design-philosophy.md
• web/troubleshooting.md
• web/usecases.md
• web/usage-scenario-examples.md

If we can get a file or directory started, I think we can land these facts in a wiki-like form in files the repo.