Make GitHub ribbon link dynamically point to specific files #4

Merged
merged 1 commit into from Jul 13, 2013

3 participants

@blaflamme blaflamme merged commit fa7ea46 into Pylons:master Jul 13, 2013
@blaflamme
Pylons Project member

thanks!

@merwok

Pretty cool!

@dslatten

Why doesn't the Edit me on GitHub ribbon link match the Edit on GitHub sidebar link?

I pointed the ribbon link to the Show on GitHub URI, as opposed to the seemingly-more-appropriate Edit on GitHub URI (see RTD sidebar) for a couple of reasons...

1. GitHub users do not expect the ribbon link to initiate a specific action.

The standard behavior of the Fork me on GitHub ribbon is to link to a repo's home page. From there, users have to click the Fork button to initiate the fork. In other words, the ribbon might link to https://github.com/Pylons/pyramid, but it would not link directly to https://github.com/Pylons/pyramid/fork. I tried to replicate this native behavior by linking the Edit me on GitHub ribbon to the specific file's show URI--from there, users have to click the Edit button to initiate the edit feature.

2. Show URIs are predictable; Edit URIs are not.


SHOW URIs

A specific file's show URI (e.g., https://github.com/Pylons/pyramid/blob/1.4-branch/docs/index.rst) returns a functional page, regardless of the user's session/authentication/authorization status on GitHub. Even if the user is not logged in, he/she will still be able to view the content, but any attempt to click the Edit button will result in a tooltip that prompts the user to log in. Either way, the show URI predictably generates a page that is useful and familiar. The following 2 images show both possible scenarios.

Scenario 1: show_file( loggedIn = TRUE )

show file, logged in

Scenario 2: show_file( loggedIn = FALSE )

show file, logged out


EDIT URIs

In contrast to show URIs, a specific file's edit URI (e.g., https://github.com/Pylons/pyramid/edit/1.4-branch/docs/index.rst) returns a completely different page, depending on (1) whether or not the user is logged into GitHub, and (2) whether or not the user has already forked that repo. The following 3 images show each possible scenario.

Scenario 1: edit_file( loggedIn = TRUE, hasFork = TRUE )

edit file, logged in, with fork

Scenario 2: edit_file( loggedIn = TRUE, hasFork = FALSE )

edit file, logged in, no fork

Scenario 3: edit_file( loggedIn = FALSE )

edit file, logged out


Why not link to the branch's home page instead?

I strongly considered keeping the Fork me on GitHub ribbon (i.e., the standard ribbon image) and changing the dynamic link code so that it points to each specific branch's home page (e.g., https://github.com/Pylons/pyramid/tree/1.4-branch), for example:

{% if display_github %}
<a href="https://github.com/{{ github_user }}/{{ github_repo }}/tree/{{ github_version }}"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://a248.e.akamai.net/camo.github.com/7afbc8b248c68eb468279e8c17986ad46549fb71/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f6461726b626c75655f3132313632312e706e67" alt="Fork me on GitHub"></a>
{% endif %}

But ultimately I decided against it, because it would have required users to navigate through the GitHub file hierarchy to find the specific page that corresponds to the RDT page they just came from (i.e., the one they're interested in editing). Depending on how they navigate to that GitHub page, the user might inadvertently change from their specific branch to the master branch (especially if they're coming from Pyramid's release-specific docs on RTD). Plus, depending on which docs they're trying to edit, the path from the branch home page to the specific file page would require at least 3 extra clicks (assuming they're using the web UI to edit the file).

@blaflamme
Pylons Project member

OTOH the «Fork me on Github» ribbon makes sense to just point out the pyramid project repo (the right branch) while I consider this top image to be something generic and not necessary a direct link to edit the current page (like an header title compared to a paragraph with context). We already have the «This Page» including three actions for looking at the source code, on github and edit.

@dslatten

To find the best solution, perhaps we should consider the various use cases that the Pylons RTD pages are intended to support. I was assuming that the links from RTD to GitHub are specifically geared toward users who are interested in contributing to the Pylons Project documentation (as opposed to users who are interested in forking a given Pylons Project code base). If that assumption is incorrect--for example, if the ribbon link on the RTD pages is the primary means of informing users that all Pylons Project code is available on GitHub--then I'd probably reconsider the href target. Another alternative might be to add the traditional GitHub ribbon to pages like these:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment