GoDoc badge

[nathany]

Provide a GoDoc badge for gophers to add to our README files alongside the badges for Continuous Integration, Code Coverage, etc.

The Sheilds.io project provides Public Domain badges, with a lot of thought put into legibility, dimensions, retina versions, and the like. This should be a good starting place.

• [ ] Discuss style and dynamic badges
• [x] Find someone with Illustrator to make the actual badges or use shielded
• [ ] Implement the necessary metrics if the badges are to be dynamic
• [x] Provide links for gophers to add the badge (ideally on each document page, with Markdown snippets in a popup, as is often done).
• [x] Provide instructions for a passing badge (perhaps on the About page, or as a popup on the project page when there is a failure)
• [ ] Handle error case when documentation hasn't been indexed for the specified url (eg. http://godoc.org/github.com/me/project/status.png)

[nathany]

A simple blue on cyan "GoDoc" badge would make me happy (MVP!). If we do want to make the badge somewhat dynamic, what would it do? I'll pitch two ideas to start.

Popularity

A metric that GoDoc already has is how many packages import a particular package. We could use this number in the badges. To avoid having hundreds of badges or needing to generate them dynamically, we could use ranges like:

0    1+    10+    20+    50+    99+

While this is a metric we already have, I personally think it would be more appropriate for a "Go Dashboard".

Documentation "Quality"

We could gather a metric to indicate how well a project is documented. Maybe something simple, like Comment line count (CLoC) vs. the total Lines of Code. The algorithm could always evolve over time. For example, maybe it puts more weight on documenting exported identifiers.

As for representation, we could use a Code Climate style GPA:

1.0    2.0    3.0    4.0

Or actual words, which would probably be more clear. :-).

Since I'm unfamiliar with the code base, I'm curious what it would take to calculate and store a metric like this?

[nathany]

I like the idea of a simple pass/fail. That will encourage everyone to have their documentation in order.

As for document quality vs. package/project quality, I suppose that depends what you envision for GoDoc?

Personally, I see GoDoc as a sort of Read the Docs for Go. I envision a stand-alone project directory that brings together metrics on documentation quality, CI builds, code quality, popularity and usage. Something inspired by The Ruby Toolbox, but with more awesome. :-)

I'm surprised that you didn't mention the Readme file. I discovered autoreadme today, but I would much rather support README.md on GoDoc or alternatively get doc.go to be a first-class citizen on GitHub and BitBucket.

P.S. I'm currently doing a survey to find out what people like to use for their Changelog filename.

[nathany]

Sounds good. So back to the question at hand: what should the criteria be for a "PASS" on GoDoc?

Package comments seems obvious to me, I'm not sure I follow the token thing at all, at least in this context. Of the project information files, which files should exist in the repository for a "PASS"?

[nathany]

Using shielded produces badges that look like this. It's very easy to change the text.

If we want to do something different for colors/design (while maintaining the dimensions and font to match other badges), I have a friend with Illustrator skills who is willing to lend a hand.

[nathany]

Nifty, a rewrite of shielded in Go https://github.com/jbowes/buckler

Instead of pass/fail, we could be a little more causal, eg. yup/nope.

[nathany]

Thanks for cluing me in, now I see where you are going. I started an fsnotify_ext repo that I DO want to see the GoDoc for, and share it so that others can see the API changes I am proposing to fsnotify, but I really don't want it in the search index because it's version 0.0.0 and nobody should be using it. In that regard, your token is like a robots.txt. But beyond that, when I go make a temporary fork of fsnotify, the token would automatically be invalid so as to not spam the search index with every fork. If a conflict of interest caused me to make my work into a stand-alone project, I would need to go fix up the token (and rename the repo to avoid confusion).

That said, I'm not entirely convinced that the GoDoc badge should represent whether or not the project is intended for sharing, especially if the label is "doc", eg. "doc: yep". There is no reason why there couldn't be multiple badges, eg. https://github.com/jbowes/buckler has a "license: mit" example. Again, I feel like what you're proposing is more a function of a Go Dashboard, though it makes sense that you would want this token to affect the search index of GoDoc as well (and gowalker, go-search, etc.).

I noticed you began extracting gosrc. I think it would be very interesting to build up a repo of packages for things like downloading source, pulling tags from github/bitbucket and validating semantic versions, parsing and validating changelogs, etc.

Maybe I'm too steeped in UNIXy philosophy, but I would see the criteria for a GoDoc badge being purely based on project documentation being in order.

To take a more iterative approach, I might even suggest using a static badge for now, and transitioning it to a dynamic one.

[nathany]

GitHub caches pages, so status images are served over HTTPS as a work-around.

[nathany]

Sounds good. Rather than using the generated badges I'm going to talk to a designer about making something similar with the Go/GoDoc colour scheme.

Just "GoDoc" in blue on cyan.

[nathany]

Here's a static badge from my good designer friend @ohoang

I'd like to set it up in such a way that we can go dynamic without anyone needing to change their README.md. I'm willing to work on the code and pull request over the weekend.

[nathany]

Regarding the token, have you walked through the process of adding a verification file for webmaster tools? https://www.google.com/webmasters/tools/home

It could follow exactly this process, except uploading this file to the root of the repo instead.

I assume that there would be nothing secret about the algorithm? The token could be generated by a web app or on the command line, and anyone who found it useful could validate it.

Is your preference for adding it to the README because GitHub has APIs to specifically grab the README? Or is there another reason?

I would love for this process to also request one or more labels be associated with repository for use I a directory.

[nathany]

Encouraging projects to have a README to place the token sounds like a good thing to me. (Ignoring that a separate file would be easier to parse).

Initially I thought of including the token in the Markdown that authors paste in for a badge. This would make it easy on package authors, though I began to reject the idea on the basis of conflating two separate things (another tool which has its own badge may wish to use the same token).

The project vs. package disparity is much wider reaching than READMEs. Tags and all the revision locking schemes (Godeps files) are at the repository level even though imports are package level. I think the best remedy is just to have many small repos.

Using notes is an interesting approach. A predefined set of categories/labels tends to be better for navigation. Allowing the author to specify arbitrary tags/keywords would probably be simpler for the author, and more flexible. A combination of stemming and some manual mapping could result in db/database/databases all ending up under the same group. Or just doing pull requests to get projects using consistent keywords.

[nathany]

Badge as the token

The badge code inside a README.md would be something like this:

[![GoDoc](http://godoc.org/badge.png)](http://godoc.org/<import path>)

Where the import path is eg. github.com/garyburd/gddo. This accomplishes what we want and the behaviour developers are likely to follow already.

• Use the badge as an indication of sharing the project (I want people to see to my docs so they can use my package).
• A temporary fork will be at a location that doesn't match the import path in the badge
• If someone updates the badge in their fork, they mean to keep it as a long-lived branch from the mainline
• This is super simple for developers, no new concept of a token. Badges in this form are standard for CI

Additionally:

• If the badge url does match the source repository location, but GoDoc hasn't indexed it, then maybe it was placed by a project generator and could be considered "not ready for sharing" as well.
• Third-party tools could do the same check against the godoc badge, or add a badge of their own, with the same logic.
• I suspect most people would accept a pull request that only modifies the README (to add the badge on their behalf).

Transition

• Projects without a README or without a badge in the README remain in the index as now
• Start checking the README and track if the badge is present and whether or not it matches
• If the badge is present but doesn't match the import path, the repo is pulled from the index and not found by searching, but still viewable by entering the url directly.
• Begin to promote the badge more heavily, by providing it from the package page (maybe get SSL first).
• Indicators in the GoDoc search results highlight projects with a badge (or matching other documentation criteria)

None of this requires the badge to dynamically indicate anything itself, though that's a logical next step.

A badge with a mismatched import path actually is very useful in that it links to the documentation for the original repo, but we should indicate that somehow on the badge (red status).

A badge that matches import paths but other documentation criteria isn't met would be less severe (yellow status).

I'd be happy to contribute to gddo-server to get the ball rolling. I imagine this is the easy stuff compared to your work on gs-lint :-). Let me know if I'm missing something with this approach. Thanks!

[nathany]

Once we have the token idea in place, I'd like to promote it, so more people adopt it and improve the search index.

GopherAcademy has been wanting guest posts, so that may be a good outlet?

[speter]

Would it be possible to enable https requests originating from project hosting pages? Using http to display the badge in https pages triggers a warning in browsers ("this page includes other resources which are not secure"). Switching the protocol to https seems to work when accessing the image directly from browser URL bar, but not from the project page (on code.google.com).

[nathany]

We really need to get this badge-based filtering happening. Including on the importers page.

Eg. http://godoc.org/github.com/howeyc/fsnotify?importers Lists everyone's fork of Revel.

[nathany]

revisiting this discussion: https://groups.google.com/forum/#!topic/golang-dev/B9POM4dm_fY

This ticket got rather lengthy. I'd like to split up what's left into new tickets that summarize what we still want.

[cznic]

Required metadata: LICENSE Recommended metadata: README End of story, IMO.

I'm no fan of such efforts to make things more complicated and over-organized than necessary or useful.

[mewmew]

It makes sense to require a README but if a project is released into the public domain a LICENSE file may not always be present. Sometimes the project will simply state this in the readme. This is true for most of my packages at least, but I'm not able to estimate how common it is.

[nf]

README or README.md is the place.

[nathany]

@mewmew Would you be willing to add a LICENSE file to your projects if GoDoc.org encouraged it?

Closing this ticket in favour of #171.

[dmitshur]

I just want to quote @garyburd here:

A large portion of the Go packages on GitHub and other services are not intended to be imported by other projects. These packages include bug fix forks, packages internal to a command and experiments. The noise created by these packages makes it difficult for people to find good packages.

I'd like to identify packages that the author intends to share and support so that these packages can rise above the noise. There are a few ways to do this.

Central registry. I like that the Go ecosystem is decentralized. I view this as a last resort.

Presence of doc shield in README. This is not a good choice because the flag propagates to forks (fork project, s/oldpath/newpath/).

Token as described above. The token does not propagate through forks (the hash will not match). It also requires that the author take action. The token can be placed in a metadata file, a comment in a source file, a query parameter for the shield, or other locations. My preference to place the token in the README file.

I have to say that is a very good and useful goal :+1:, I support it fully. Also agree about central registry, while it may do what's needed, it'd be much better if the goal can be accomplished another way.

[mewmew]

@nathany As mentioned in issue 171 I like the fact that the Go toolchain has made it possible to get rid of most files not directly related to the technical aspects of a project, such as configure scripts and Makefiles. For the same reason I prefer to give a short public domain notice in the README rather than creating a dedicated LICENSE file.

If GoDoc.org encouraged adding a LICENSE file to each public domain repository I would consider it. Obviously I wish we could find a solution that didn't force it. If no LICENSE file is present, perhaps fallback to a fuzzy search of the README. But lets continue the discussion in issue #171.

[Aparnarr]

HI godoc is not rendering correctly?? any updates??