[benbalter]

We may make things more flexible down the line, but for now, it was motivated by two primary reasons:

1. The overwhelming majority of users use one of those three design patterns. For example, I can tell you that more than 98% of GitHub Pages sites use either `master` or `gh-pages` as their primary branch (with only about one tenth of one percent of sites using the `stable` branch).

2. Our experience tells us that every option we add to GitHub Pages increases the learning curve for newer developers. With only those three options, if you're just learning HTML, you don't need to understand Git's branching model before you can create your first website.

We chose these options to start because we thought they struck a good balance between supporting collaborative documentation workflows for open source projects and encouraging "hello world" experimentation among new developers, but as with most features at GitHub, this is just the start.

[bsimpson]

That's what defaults are for.

You have two choices to make: which branch and which path within that branch. The defaults are "master" and "docs," but allowing maintainers to make different choices there doesn't need to impact the onboarding experience for new developers. The newbies use the defaults - people who need customization can customize. Software development is a broad field and projects work within various constraints and architectures. Asserting a convention here feels a bit misguided.

You already allow the default branch to be customized. It's a bit weird that I can specify a default branch (like "develop") and delete the master branch, but then won't be able to publish docs without recreating master or maintaining a gh-pages branch.

[madgar]

> Asserting a convention here feels a bit misguided.

Expecting GitHub to spend real money to cater to a tiny minority of users of their web service is misguided. The business models behind public internet services are simply not structured to cater to anything but the lowest/simplest common denominator users.

[bsimpson]

I expect a reasonable amount of flexibility in developer tools, especially since the difference between the current solution and the customizable one is most likely two inputs in a web form.

It's great to see new features shipping on GitHub.com (especially since it felt stagnant for so long). I have no idea what their codebase looks like, but prepopulating a text field with the contents of a template.md file and allowing the name of the publishing branch to be specified feel like they should have been fairly minor changes. Especially now that they clearly have the architecture to choose repo-specific publishing locations, allowing those to be user-specified should be a very low-effort way to make the tools useful for more projects.

[kidsil]

> Expecting GitHub to spend real money to cater to a tiny minority of users

You must be new here...

[brandonbloom]

Great! Please don't give in to the demand for added flexibility without strong justification. Just as it did with README.md, GitHub has an opportunity to drive successful conventions and global simplifications that virtually no other organization in open source can.

[nzp]

I'm not sure if you're being sarcastic, but README file was a convention for decades literally.

[brandonbloom]

Not sarcastic at all. First, I said README.md. Markdown in readmes was popularized - if not invented by - GitHub. Furthermore, the top billing of README.md files in the GitHub UI took over from more traditional meta-level documentation that used to be in separate places, such as an "About" field/page on SourceForge or a separate web page. I much prefer this documentation in repository. Even if projects had READMEs, they might not include certain information there previously.

[nzp]

All these things are just GitHub's implementation and UX details. The README file is the traditional meta-level documentation (if I correctly understand what you mean by that: top level document that gives a more or less comprehensive overview of the project). READMEs always included this information, sometimes offloading details of particular topics into INSTALL, AUTHORS, LICENCE, etc. files. GitHub just figured they might as well use the thing as intended and actually render it on a web page. As for markup, people were already using email like markup in those files, so this is again just following established practice to its logical conclusion and modern implementations. GH's sole innovation in convention here is tacking on the very annoying file type extension in order to not have to figure out the format automatically.

[aorth]

Thank you for making a sane default based on actual usage data. BTW, for people who need something a bit different, I have been using this for one of my sites that is hosted on GitHub:

  $ git subtree push --prefix=public origin gh-pages

The `public` directory is where the HTML/CSS/JS generated by my static site generator and I push that subtree to the gh-pages branch.

[mintplant]

Favorited for later. Thanks, that's useful!

[sn0v]

Personally speaking, I think this is a great idea. Great job!

[cpeterso]

Why /docs instead of something more encompassing like /site or /pages?