Add an "Edit this page on GitHub" badge?

[erget]

Originally posted by @ethanrd in https://github.com/cf-convention/cf-convention.github.io/issues/116#issuecomment-641588870 (abridged):

I'll add two issues: 1) add "Edit this page on GitHub" badge; 2) Move to standard GHPages template.

This issue is to add an "Edit this page on GitHub" badge, I'll raise another one for the page template.

[erget]

In support: Makes it really easy to edit pages for contributors (e.g. https://github.com/cf-convention/cf-convention.github.io/issues/116#issuecomment-641552986)

Reasons against: Potentially people would submit PRs without issues, bypassing processes (https://github.com/cf-convention/cf-convention.github.io/issues/176#issuecomment-924033387)

This was implemented in https://github.com/cf-convention/cf-convention.github.io/commit/f1f94b883e3ff180be80761db3c9713eae329186 with a couple of other updates. I have asked @cofinoa to revert the specific change to the footer until we can decide (hopefully quickly) how to approach this via consensus. If we do decide to keep a link (even if it's presented differently on the page) we can steal the code off of that commit, since it's handy.

I'd be interested in hearing thoughts on this. I personally am in support of having such a link or banner on each page, because it makes it easier to prepare a PR, which can then be associated to an issue.

[JonathanGregory]

Repeating myself from https://github.com/cf-convention/cf-convention.github.io/issues/176#issuecomment-924033387:

I think it's better to direct people to the Discussion page, because our rules don't invite people directly to edit pages (by opening pull requests to modify the website) without first opening a GitHub issue, as is explained on the Discussion page.

In https://github.com/cf-convention/cf-convention.github.io/pull/175 I now have the footer text "Contact the CF community with questions, comments and suggestions about CF metadata or this website" as a link to the CF Discussion page. If you click on that link because you want to suggest a change to the website, you will see "For discussing, proposing changes and reporting defects in the CF website, and for discussion of CF governance", which provides a link to the issues in the website repo. I think that's a pretty easy and obvious route, isn't it?

[davidhassell]

Hi @erget, you wrote "[...] such a link or banner on each page, [...] makes it easier to prepare a PR [...]". I was wondering what the endpoint of "Edit this page on GitHub" would be - is it https://github.com/cf-convention/cf-conventions?

[erget]

@JonathanGregory @davidhassell the issue is that in order to edit the webpage currently, you have to understand how it's built and deployed, or at least be able to guess. This happens to be (fairly) straightforward in our case - a tree of Markdown documents with corresponding HTML documents. However, that's not necessarily the case. Having such a link takes you from the HTML page to the corresponding Markdown page directly.

@davidhassell you can check it while we're waiting for @cofinoa to revert the changes - it's a link that is specific to each page. In Markdown that's described here:

<a href="{{ site.github.repository_url }}/edit/master/{{ page.path }}">Edit this page on GitHub!</a>

So that e.g. for the main page that resolves to https://github.com/cf-convention/cf-convention.github.io/edit/master/index.md and for other pages it resolves to the corresponding page, rather than requiring people to go to the repository and then find the right page.

My suggestion is to try it out while the functionality's still there - I expect it'll disappear quickly, since I'll merge it as soon as Antonio proposes the revert - and you can see how handy it is to have such a link.

[JonathanGregory]

Dear Daniel @erget

I agree that it's clever and a convenient way to get to the source, and thanks for pointing it out, but doesn't it tacitly encourage anyone to think the right procedure is to edit the page and submit a PR, if they're not familiar with our rules? Especially if this is exactly what they're used to doing in other GitHub organisations. If the main convenience of it is being told where to find the source of the web pages, we could provide that information on the Discussion page. As you say, the mapping is pretty easy for the markdown pages.

By the way, I think it would be helpful to add a statement in README of the website repo directing visitors to the Discussion page and the website issues page if they want to suggest a change to the website. The README of the conventions repo has a notice like that.

Best wishes

Jonathan

[davidhassell]

Thanks, Daniel, that's very useful know. I'm currently torn between the various compelling arguments.

If we added we add a PR template that that contains something like:

Fixes: #???

• [ ] Issue created for discussing these changes

Would that help instruct the casual editor?

[erget]

Hi @davidhassell , I don't know if that would work in our situation. In order to find out I just did a test by clicking the button, creating a bogus commit, and then submitting a merge request straight off of that. The PR text was pre-populated with my commit text.

Do you think that this is a potential danger for CF? I see the following potential worries but don't actually see an impact on us due to the safeguards we already have in place

Potential misunderstanding of process	Worst outcome that could occur due to misuse
User wants to commit directly to main	This would be unusual since all projects automatically have write safeguards. That includes us. Therefore the user would have no option but to open a branch and corresponding PR
User submits PR without being aware of our processes	One of the repo maintainers sees the PR and advises the user of our change processes, pointing them toward their description and requesting that the open an issue that references the PR.

This is also taking into consideration the fact that we don't generally have a high edit volume on this repository.

Note also that this applies only to editing the webpage, not the Conventions or Conformance documents!

[JonathanGregory]

Dear Daniel @erget

Is this much more convenient than navigating to the repo and editing there? - that is possible, isn't it? Going via that route, you would see the README of the repo, which should advise on the procedure.

Perhaps "Edit this page" could invoke a program which would produce a page that explained the procedure, and gave a link for opening a new issue, and another link for actually editing the page. That would work if that GitHub magic markdown could be used to generate an argument to the program. Perhaps such a thing can be done in javascript, which is a language I don't know but no doubt many among us do! (I could do it in php. :smile: )

Jonathan

[larsbarring]

This is really way out of my expertise, but could the "Edit this page" be associated with a mouseover/hover over text displaying something like "You may suggest changes, but please note that there has to be an associated issue explaining the changes"

[erget]

Hi @JonathanGregory @larsbarring, excuse my curtness, this is due to the lateness of a Friday afternoon and not my mood :)

From @JonathanGregory:

Is this much more convenient than navigating to the repo and editing there? - that is possible, isn't it? Going via that route, you would see the README of the repo, which should advise on the procedure.

The way I see it, most definitely. I propose you try it out - especially if you're not familiar with the website, it can be difficult to navigate the inner workings of the GitHub repo. What seems obvious to us may not in fact be obvious. Especially because other GitHub users are used to having such "Edit this on GitHub!" tags.

Perhaps "Edit this page" could invoke a program which would produce a page that explained the procedure, and gave a link for opening a new issue, and another link for actually editing the page. That would work if that GitHub magic markdown could be used to generate an argument to the program. Perhaps such a thing can be done in javascript, which is a language I don't know but no doubt many among us do! (I could do it in php. 😄 )

Yes... Certainly possible. In terms of cost vs. benefit I think we would invest a lot of effort in doing this for little return. In that case we may as well simply link "Edit this on GitHub!" to the "Rules" page, which would probably make some users feel trolled or at least rick-rolled... And in that case we could probably as-well simply call the link "Edit this page", but in that case we could just leave it of altogether.

From @larsbarring:

This is really way out of my expertise, but could the "Edit this page" be associated with a mouseover/hover over text displaying something like "You may suggest changes, but please note that there has to be an associated issue explaining the changes"

Certainly... Not hard to do. I'm not convinced this is useful.

My conclusions

I think that we may be investing a lot of effort in fixing a problem that doesn't really exist. What's the worst that could happen? People issue pull requests and then we, as reviewers, comment in the pull request that they should open a corresponding issue, if they haven't found the rules. Note that when creating a pull request, GitHub refers the users automatically to our contribution guidelines, which contain the rules. So all users are duly warned anyway.

As things stand, it's not horrible, but we have the opportunity to make engaging with the Conventions and their presentation on the website much easier, without risking that changes are made in an uncontrolled fashion, and thus I am in favour of allowing this, especially considering the fact that we already have the (admittedly simple, but very useful) code kindly provided by @castelao that would do this.

Although I personally would not profit from implementing this in particular, I believe that the community would - it would make us that much more open and approachable, and without cost.

If I'm the only one who's interested in this I'm also willing to drop it, although I would find it a bit sad. Perhaps some other heavy GitHub users could give their perspectives? E.g. @DocOtak @dblodgett-usgs @ethanrd @sadielbartholomew ...

[ethanrd]

Hi all - I agree with Daniel that the advantage of having "Edit this page" links far outweigh the disruption it is likely to cause.

[davidhassell]

Hi - I also agree with Daniel's conclusions, and would be happy with the "edit this page" feature. We (? well I) don't expect much traffic from this, and a simple "please raise an associated issue" is therefore no bother.

[JonathanGregory]

Since others are keen on it, and I don't feel strongly, I'm willing to agree. If it does cause any problem we can think again. Jonathan

[sadielbartholomew]

Daniel, all, (with apologies for the late reply, I was on leave) I also think the "Edit this page on GitHub" badge is a good idea and would be beneficial overall. :+1:

[erget]

Thanks all for your comments - I've implemented this in the associated PR. Could somebody check and approve if you're happy? I propose we merge after 3 weeks since this isn't a simple error correction.

[sadielbartholomew]

Could somebody check and approve if you're happy?

Hi @erget, great stuff, I've assigned myself and will get it reviewed (but not merge it even if I approve immediately).

[erget]

Thanks @sadielbartholomew ! I will merge this on 2021-11-24.