2 ms·

You make some important points. Let's go through that list and try to figure out how to make things better: > Stable, versioned releases, with sufficient API (

by pjscott 15y ago

You make some important points. Let's go through that list and try to figure out how to make things better: > Stable, versioned releases, with sufficient API (if not ABI) compatibility across releases. When people do this on GitHub, the usual method is to create a release tag for each version. GitHub offers tarballs of the repo at each version tag, and can quickly switch views of the code. I try to always use proper semantic versioning once my software reaches maturity, and I've never noticed GitHub getting in the way of that. > Accurate and complete API documentation (with bonus points for higher-level integration documentation. There are a variety of Right Ways to do this, and it varies by language. In Haskell, for example, the most popular form of API documentation is automatically generated from the code and specially-formatted comments by Haddock. For other languages, there are various competing ways of doing API docs, from writing the stuff manually up through a number of doc extraction tools. I think the ideal way for GitHub to handle this would be to introduce a separate docs repo for each project, serve up the generated HTML, and put out some tools for updating it. This is similar to what they do with project wikis. This would require the cooperation of external tools to be easy, but the GitHub guys have enough fame that they could probably start a flood of tools if they just get it started. > A bug tracking system GitHub has a rudimentary form of this, but it would be nice if they could insert prominent links to external bug trackers, so people could use their favorite one. Barring that, sticking a clearly-labeled link in the top-level readme file is a decent approximation. > Mailing lists. Google Groups is a decent approximation of this. Again, it would be nice if there were a standard way to insert links to external mailing list pages in GitHub projects. Any more problems or solutions?

bad_user 15y ago
the ideal way for GitHub to handle this would be to introduce a separate docs repo for each project In a GitHub project you can create a gh-pages branch. In this branch you can place HTML files that will get rendered at http://username.github.com/project-name/ http://username.github.com/project-name/ ... This is automated by GitHub in the Admin tab of any project. Simply select the option GitHub Pages and it will generate a branch with a basic index.html for you, that also has a download link. See http://pages.github.com/ http://pages.github.com/ for more details.

by pjscott 15y ago

bad_user 15y ago

the ideal way for GitHub to handle this would be to introduce a separate docs repo for each project In a GitHub project you can create a gh-pages branch. In this branch you can place HTML files that will get rendered at http://username.github.com/project-name/ http://username.github.com/project-name/ ... This is automated by GitHub in the Admin tab of any project. Simply select the option GitHub Pages and it will generate a branch with a basic index.html for you, that also has a download link. See http://pages.github.com/ http://pages.github.com/ for more details.