[PATCH] wwwdocs: document scripts to access personal and vendor spaces

[Richard Earnshaw (lists)]

On 24/01/2020 12:19, Jonathan Wakely wrote:
> On 24/01/20 11:48 +0000, Richard Earnshaw (lists) wrote:
>> On 24/01/2020 11:04, Jonathan Wakely wrote:
>>> On 23/01/20 16:23 +0000, Richard Earnshaw (lists) wrote:
>>>> On 21/01/2020 18:58, Richard Earnshaw (lists) wrote:
>>>>> This patch documents some of the scripts that I've published for 
>>>>> managing the personal and vendor spaces on the server.  It also 
>>>>> covers some of the other features that those scripts enable, so 
>>>>> that it's all in one place.  This is a complete rewrite of the 
>>>>> material I had written previously since before we did not have 
>>>>> these scripts to make use of.
>>>>>
>>>>> I've not filled in the documentation for gcc-descr and gcc-undescr, 
>>>>> Jakub has agreed to provide that at a later date.
>>>>>
>>>>> R.
>>>>
>>>> I've pushed this.  I think it's better to have this in than nothing 
>>>> at all.  We can iterate on it as required.
>>>
>>> I've pushed the attached fix for a couple of typos.
>>>
>>> Do we want to repeat the "do not push changes to that space without
>>> their express permission" for user branches? There are no access
>>> checks to prevent it, but I hsouldn't be changing things in your
>>> branches without your permission.
>>>
>>
>> Absolutely.  I guess I took this as read in the personal spaces.
> 
> If we don't document it, somebody will get it wrong :-)
> 
> Maybe like so, after the "To create a new personal branch" paragraph:
> 
> <p><em>Personal spaces are controlled by the individual user.  Do not push
> changes to somebody else's space without their express permission.</em>
> (Rather than pushing to somebody else's personal branch, consider pushing
> to your own personal branch and having collaborators pull from there).
> </p>
> 
> Is the parenthesis going into too much detail, too early? This page
> doesn't describe how to pull from somebody else's personal branch (and
> arguably that would be too much info here anyway, but it might make
> sense for https://gcc.gnu.org/wiki/GitCookbook instead).

I think the 'pull' model is probably preferable for personal spaces.  At 
some point we might need to enforce something like that anyway.

> 
> So maybe just the part in <em>.
> 
>>> Finally, why does this qualify it as "If you have multiple clones"?
>>>
>>> <p>If you have multiple clones of the gcc repository you can fetch
>>> updates from your personal space by running
>>> Â  <code>git fetch me</code>
>>>
>>> Isn't that the right command even if you only have one clone?
>>>
>>
>>
>> Well, if you only have one clone, why would you need to pull branches 
>> from upstream that you pushed yourself?
> 
> Good point.
> 
>> In fact, why would you even need to push them in that case, unless 
>> it's for backup?  ... and if 
> 
> So other people can see your work in progress (without the overhead of
> setting up a devel/* branch for a short-lived topic branch).
> 
>> you're restoring your backup, then that's a new clone.  You might 
>> temporally have only only one clone, but across all time you have more 
>> than one.
> 
> Right. I was stuck in small-minded, non-distributed thinking :-)
> 
>> It's pedantry, though, so feel free to re-word it.
> 
> How about:
> 
> "You can fetch updates from your personal space into some other clone
> of the repository (e.g. on a machine used for testing) by running:"
> 
> 

Yes, that's fine.

Note, that I spotted a problem with the simple "me" remote, in that git 
gets confused if you have both refs/heads/<me>/<topic> and 
refs/remotes/<me>/<topic> (checking out me/<topic> results in complaints 
about an ambiguous ref).  I'm currently reworking my scripts to use 
users/<me> for the remote, much like the 'vendors' space.  Watch this 
space...

R.