Re: Why are so many great packages not trying to get included in GNU Emacs?

[Tim Cross <theophilusx@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 8731 bytes --]

On Sat, 25 Apr 2020 at 18:33, Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Tim Cross <theophilusx@gmail.com>
> > Date: Sat, 25 Apr 2020 17:56:48 +1000
> > Cc: Eric Abrahamsen <eric@ericabrahamsen.net>, Yuan Fu <
> casouri@gmail.com>,
> >  ndame <ndame@protonmail.com>, Stefan Monnier <monnier@iro.umontreal.ca
> >,
> >  Emacs developers <emacs-devel@gnu.org>
> >
> >  If this is meant as a way to implement pull requests, there is no need
> >  for it.  We will not implement pull requests by copying proposed
> >  patches into our repo before they are installed.
> >
> > There seems to be some confusion regarding 'pull requests'.
>
> There definitely is, but let's not exacerbate the situation by using
> confusing inconsistent terminology.
>
> > When you look at it, all a pull request is is a request to merge a
> > branch from another repo into your repo.  Nothing is added to your
> > repo until you perform the merge.
>
> It should be clear that Richard is talking about 2 things:
>
>   . the location (i.e. the hosting server) where that "other"
>     repository lives
>   . the process of merging the PR
>
>
No, it is not clear. What I got from a number of Richard's posts was the
concern that a PR would appear to be part of the GNU Emacs distribution or
in some way mistaken as being 'official' or agreed to. What I was trying to
make clear is that the PR has NO impact on the repository in itself. It is
only after someone takes that pull request and merges it into the
repository that it becomes part of the repository. A PR in itself is just a
request to merge changes. It is effectively no different from sending an
email with a patch in it except it is more public (or at least can be). As
the PR is hosted in a completely separate repository, there is no chance it
can be confused or seen as being part of the official repository.


> > Basically, you add
> > the PR repository to your LOCAL repo
>
> How can you "add a repository to a repo"?  (And why use two different
> words, "repository" and "repo", to indicate the same thing?)


repo is shorthand for repository. It is a term in common usage and I think
pretty obvious.


> Don't
> you mean to say "you fork a repository", i.e. clone the repository to
> produce a separate one, in another directory on the local system?
>
>
Definitely not! You do not need to clone the PR repository. You can add the
PR repository to your local clone as another upstream source. This is part
of what makes PRs so easy to work with. Once you have aded the PR
repository to your clone, you can checkout a branch from that repo in your
clone. From this point, merging is just normal merging of branches in your
clone. Nothing is seen in the upstream repo until you do a push.


> and check it out as a branch. Do whatever you need (review, fix, etc),
> > commit it to your local repository. Perhaps do some diffs against your
> master repository and if all is good,
> > merge it with your local master branch. At this point, there is still no
> change to the 'main' master repository.
> > If the merge all goes fine, you can then push the changes to your master
> branch in your main repository. It is
> > only at this point that the changes have been introduced to the main
> repository.
> >
> > So, in short, making a PR has NO impact on the master repository until
> someone with write permission ie.g.
> > the owner, merges the PR into the master repository.
>
> And here you use "master repository" without defining what that is,
> and then use "main master repository" as if it were a different thing
> (is it?).  Should we be surprised that people get confused?
>
>
Fair enough. I will try to clarify and define the terms to make it clearer.


> I think there are 3 repositories involved in this story:
>
>   . the upstream repository, which lives on Savannah
>   . the local clone of the upstream repository on the user's machine
>   . the "forked repository", which is a clone of the clone mentioned
>     in the previous item; this forked repository is also local, and it
>     is where the user makes the changes which will be the subject of
>     the PR
>
> So far so good?
>

No, not quite. We do have 3 repositories, but not quite as you have defined
them.

1. The upstream repository which lives on Savannah. Let's call this the
master repository.
2. Local clone of master repository used by a maintainer. Call this one the
maintenance repository
3. A developers fork of the master repository. This can be anywhere, but
needs a public interface, like https (i.e. github, gitlab, bitbucket etc).
Call this the developers repository.

There is not much difference between a fork and a clone. A fork typically
refers to a clone of a repository which itself is made available for
further cloning/forking on a server somewhere. Changes can be made on the
forked clone, but typically the changes cannot be pushed upstream to the
master repository the forked repository was cloned from. The 3rd repository
above needs to be a fork because it needs to be public and available to
perform a merge following a pull request.

A maintainer is someone who has write access to the master repository
A developer is someone who would like to contribute code. They have read
access (can clone) from the master repository, but do not have write access.

The PR consists of two workflows, the developers workflow and the
maintainers workflow.

The developers workflow is roughly

1. Fork the master repository to some location, creating the developer
repository.
2. Clone the developer repository so that the developer now has a local
repository to work on
3. Make changes and when complete, push to the developers repository.
Often, the changes will be in a feature branch. It would also be normal
practice for the developer to make sure their forked copy is up-to-date and
their changes in their feature branch have been merged with the current
state of the upstream code i.e. pull from upstream, merge master with
feature branch.
4. Make the PR. How this is done would depend on what interfaces are
available, but could be as simple as an email to the maintainer which
requests that the maintainer pull their changes from their developer
repository and merge them into the master repository. The email would need
to include the URL for the developer repository and include any branch
information if required i.e. the changes might be in a feature branch
within the developer repoository.

 The maintainer workflow could be something like

1. Maintainer receives the PR from the developer (how depends on what
interfaces are available, but might just be an email).
2. Maintainer adds the developers repository as another upstream source to
their LOCAL maintenance repository.
3. Maintainer checks out the developers PR branch as a local branch in
their working directory
4. Maintainer does whatever reviews, cleanup, adjustments etc they think
are necessary and commits the branch. This only commits to their local
maintenance repository.
5. Maintainer does any other check, such as verifying copyright or whatever
6. Maintainer now checks out master branch of maintenance repository
(possibly after doing a pull from upstream master repository to ensure
latest code base).
7. Maintainer then merges local PR branch into master branch
8 Maintainer runs tests and verifies merge is good and if happy commits the
master to local maintenance repository with appropriate commit message.

At this point, the PR is only in the local maintenance repository. There
has not yet been any changes made to the master repository, so nobody can
see these changes.

9. Maintainer pushes the local master branch to the upstream master
repository

The maintainer may then choose to do some cleanup work, like removing the
PR branch and PR upsream source from their local maintenance repository (or
they can leave them, they don't use much space and you may get further PRs
from that developer etc).


If so, as previous discussions have established, the issue that is of
> concern is what server should host the "forked repository".  It
> cannot be someone's private machine, because private machines don't
> usually have Git servers, and thus cannot be pulled from.  Richard
> also didn't want this to be Savannah, because then the forked
> repository and its changes could be perceived as "endorsed" by GNU.
> The practical solution is to host this on some nongnu.org server.
>
>
I don't think we need to care. Provided the person making the PR is able to
provide a public interface to their repository, it doesn't matter where it
is hosted. Once the PR is complete, the code is part of the master
repository and the forked developer repository is irrelevant.


-- 
regards,

Tim

--
Tim Cross

[-- Attachment #2: Type: text/html, Size: 11470 bytes --]