Merge pull request #4831 from mattip/faq-update

DOC: update FAQ for move to github

pypy/doc/faq.rst

@@ -484,11 +484,13 @@ the GC and possibly the JIT.
 .. _git:
 .. _github:
 
-Why doesn't PyPy use Git and move to GitHub?
----------------------------------------------
+Why did PyPy switch to Git and move to GitHub?
+----------------------------------------------
 
-We discussed it during the switch away from bitbucket.  We concluded that (1)
-the Git workflow is not as well suited as the Mercurial workflow for our style,
+PyPy moved from SVN to `Mercurial and bitbucket`_ in 2010. In 2020, when
+bitbucket summarily dropped support for Mercurial, we debated whether to move
+to Git/GitHub.  At the time we concluded that (1) the Git workflow is not as
+well suited as the Mercurial workflow for our style,
 and (2) moving to github "just because everybody else does" is a argument on
 thin grounds.
 
@@ -498,20 +500,31 @@ concept.  Git has *branches,* of course, which in Mercurial are called
 bookmarks.  We're not talking about bookmarks.
 
 The difference between git branches and named branches is not that important in
-a repo with 10 branches (no matter how big).  But in the case of PyPy, we have
-at the moment 1840 branches.  Most are closed by now, of course.  But we would
+a repo with 10 branches (no matter how big).  But in the case of PyPy, we had
+at that moment 1840 branches.  Most are closed by now, of course.  But we would
 really like to retain (both now and in the future) the ability to look at a
-commit from the past, and know in which branch it was made.  Please make sure
-you understand the difference between the Git and the Mercurial branches to
-realize that this is not always possible with Git--- we looked hard, and there
-is no built-in way to get this workflow.
+commit from the past, and know in which branch it was made.  There is a
+difference between the Git and the Mercurial branches and that this is not
+always possible with Git--- we looked hard, and there is no built-in way to get
+this workflow.
 
 Still not convinced?  Consider this git repo with three commits: commit #2 with
 parent #1 and head of git branch "A"; commit #3 with also parent #1 but head of
 git branch "B".  When commit #1 was made, was it in the branch "A" or "B"?
 (It could also be yet another branch whose head was also moved forward, or even
 completely deleted.)
 
+Soon after this discussion, we discovered `git notes`_, which allow annotating
+each git commit with a note indicating its origin branch. While this is not a
+perfect solution, it does somewhat soften the blow.
+
+Our development efforts pivoted to integrate PyPy into the Open Source project
+space: PyPy began to be tested on many popular python projects, including
+availability on conda-forge_. This meant it became important to lower friction
+in the interactions with other development groups. It turns out most of them
+use GitHub, which only uses Git. So at the end of 2023 we `moved to
+Git/GitHub`_ for our main development. The repos that do not have as much
+public interaction still remain at https://foss.heptapod.net/pypy/.
 
 What is needed for better Windows 64 support of PyPy?
 -----------------------------------------------------
@@ -533,3 +546,8 @@ How long will PyPy support Python2?
 Since RPython is built on top of Python2 and that is extremely unlikely to
 change, the Python2 version of PyPy will be around "forever", i.e. as long as
 PyPy itself is around.
+
+_ `Mercurial and bitbucket`: https://www.pypy.org/posts/2010/12/pypy-migrates-to-mercurial-3308736161543832134.html
+_ `git notes`: https://git-scm.com/docs/git-notes
+_ `conda-forge: https://www.pypy.org/posts/2022/11/pypy-and-conda-forge.html
+_ `moved to Git/GitHub`: https://www.pypy.org/posts/2023/12/pypy-moved-to-git-github.html