> From: Tim Cross <address@hidden>
> Date: Sat, 25 Apr 2020 17:56:48 +1000
> Cc: Eric Abrahamsen <address@hidden>, Yuan Fu <address@hidden>,
> ndame <address@hidden>, Stefan Monnier <address@hidden>,
> Emacs developers <address@hidden>
>
> 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.