[libvirt PATCH] docs: add 'edit this page' link to footer of every page

[Daniel P. Berrangé]

On Wed, Apr 08, 2020 at 06:08:59PM +0200, Ján Tomko wrote:
> On a Wednesday in 2020, Daniel P. Berrangé wrote:
> > To encourage contributors to make changes to the main website, add a
> > footer link to every page which links to the corresponding source file
> > in git. With gitlab, they are able to edit content directly in the web
> > browser and then submit a merge request.
> 
> Should this patch wait until we switch to merge requests for libvirt?
> 
> (Also, for repositories where I can push directly, the text about
> opening a merge request is not present and pressing 'submit changes'
> pushes a commit to master right away - can notifications be set for
> push events too? I don't seem to be getting any, despite setting
> 'watch' for the libvirt project)

If you click the "watch" icon against a proiject and select "custom"
you can see a list of the event types that it can send on, and there's
no mention of "direct pushes". So I don't believe this is possible.

With current setup those with direct commit privs on libvirt
can directly commit from the web UI. We must trust them not to
abuse that, as we trust them not to abuse their CLI based push
privileges.

3rd parties without commit privs will be prompted to fork the
repository when they press the "Edit" button, before they can
make changes. After that they'll need to submit the changes
back to libvirt, in accordance with our stated contribution
policy.

So although my commit message here talks about merge requests,
for now we'd still expect email submission. They should just
follow whatever we state in CONTRIBUTING.md if they're playing
nicely.

Once we do switch to a merge request flow, the branch protection
rules can be set to forbid direct pushes, and that means even
libvirt maintainers will have to go for the fork route in the
same way as 3rd parties do today.


> > This gives a way to contribute
> > content that is arguably easier than our wiki which requires manual
> > account creation, while this will also benefit from maintainer review.
> > 
> > Signed-off-by: Daniel P. Berrangé <berrange at redhat.com>
> > ---
> > docs/Makefile.am | 5 +++++
> > docs/page.xsl    | 7 +++++++
> > docs/site.xsl    | 1 +
> > docs/subsite.xsl | 1 +
> > 4 files changed, 14 insertions(+)
> > 
> > @@ -150,6 +151,12 @@
> >           </div>
> >         </div>
> >         <div id="footer">
> > +          <div id="contact">
> > +            <h3>Contribute</h3>
> > +            <ul>
> > +              <li><a href="https://gitlab.com/libvirt/libvirt/-/blob/master/docs/{$pagesrc}">edit this page</a></li>
> 
> Consider s/blob/edit/ to go directly to the editing page, at the cost of
> showing the gitlab login page instead of the source file to users who
> aren't logged in.

That URL change only makes a difference for the few of us who have
direct commit privileges to libvirt. For anyone else, if they
follow the /edit/ link, they'll get redirected to the /blob/
linnk again, and prompted to fork the repo. Given that /edit/
has the downside of showing the login screen, and the main
target audience is 3rd party people, not main libvirt maintrainers,
I think we can just stick with /blob/

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|