[pypy-commit] pypy heptapod: start to migrate documentation to foss.heptapod.net and document new workflow
mattip
pypy.commits at gmail.com
Tue Feb 11 12:09:40 EST 2020
Author: Matti Picus <matti.picus at gmail.com>
Branch: heptapod
Changeset: r98697:46525488dc8f
Date: 2020-02-11 19:07 +0200
http://bitbucket.org/pypy/pypy/changeset/46525488dc8f/
Log: start to migrate documentation to foss.heptapod.net and document new
workflow
diff --git a/pypy/doc/build.rst b/pypy/doc/build.rst
--- a/pypy/doc/build.rst
+++ b/pypy/doc/build.rst
@@ -37,7 +37,7 @@
You must issue the following command on your
command line, DOS box, or terminal::
- hg clone http://bitbucket.org/pypy/pypy pypy
+ hg clone http://foss.heptapod.net/pypy/pypy pypy
This will clone the repository and place it into a directory
named ``pypy``, and will get you the PyPy source in ``pypy/pypy`` and
diff --git a/pypy/doc/contributing.rst b/pypy/doc/contributing.rst
--- a/pypy/doc/contributing.rst
+++ b/pypy/doc/contributing.rst
@@ -71,43 +71,57 @@
* Missing language features - these are listed in our `issue tracker`_
.. _nightly builds: http://buildbot.pypy.org/nightly/
-.. _issue tracker: https://bitbucket.org/pypy/pypy/issues
+.. _issue tracker: https://foss.heptapod.net/pypy/pypy/issues
Source Control
--------------
-PyPy development is based a typical fork/pull request based workflow, centered
-around Mercurial (hg), hosted on Bitbucket. If you have not used this workflow
-before, a good introduction can be found here:
+PyPy's main repositories are hosted here: https://foss.heptapod.net/pypy.
- https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow
+`Heptapod <https://heptapod.net/>`_ is a friendly fork of GitLab Community
+Edition supporting Mercurial. https://foss.heptapod.net is a public instance
+for Free and Open-Source Software (more information `here
+<https://foss.heptapod.net/heptapod/foss.heptapod.net>`_).
-The cycle for a new PyPy contributor goes typically like this:
+Thanks to `Octobus <https://octobus.net/>`_ and `Clever Cloud
+<https://www.clever-cloud.com>`_ for providing this service!
-Fork & Clone
+.. raw:: html
+
+ <h1 align="center">
+ <a href="https://foss.heptapod.net/heptapod/foss.heptapod.net">
+ <img width="500" alt="Octobus + Clever Cloud"
+ src="https://foss.heptapod.net/heptapod/slides/2020-FOSDEM/raw/branch/default/octobus+clever.png"
+ >
+ </a>
+ </h1>
+
+If you are new with Mercurial and Heptapod, you can read this short tutorial:
+
+.. toctree::
+ :maxdepth: 1
+
+ mercurial_heptapod
+
+
+Clone
------------
-* Make an account on bitbucket_.
-
-* Go to https://bitbucket.org/pypy/pypy/ and click "fork" (left
- icons). You get a fork of the repository, e.g. in
- `https://bitbucket.org/yourname/pypy/`.
-
-* Clone your new repo (i.e. the fork) to your local machine with the command
- ``hg clone ssh://hg@bitbucket.org/yourname/pypy``. It is a very slow
+* Clone the PyPy repo to your local machine with the command
+ ``hg clone https://foss.heptapod.net/pypy/pypy``. It is a very slow
operation but only ever needs to be done once. See also
http://pypy.org/download.html#building-from-source .
- If you already cloned
- ``https://bitbucket.org/pypy/pypy`` before, even if some time ago,
+ If you already cloned the repo before, even if some time ago,
then you can reuse the same clone by editing the file ``.hg/hgrc`` in
your clone to contain the line ``default =
- ssh://hg@bitbucket.org/yourname/pypy``, and then do ``hg pull && hg
+ https://foss.heptapod.net/pypy/pypy``, and then do ``hg pull && hg
up``. If you already have such a clone but don't want to change it,
you can clone that copy with ``hg clone /path/to/other/copy``, and
then edit ``.hg/hgrc`` as above and do ``hg pull && hg up``.
-* Now you have a complete copy of the PyPy repo. Make a branch
- with a command like ``hg branch name_of_your_branch``.
+* Now you have a complete copy of the PyPy repo. Make a long-lived branch
+ with a command like ``hg branch name_of_your_branch``, or make a short-
+ lived branch for a simple fix with a command like ``hg topic issueXXXX``.
Edit
----
@@ -138,14 +152,14 @@
locally present.
* You should push often; there is no real reason not to. Remember that
- even if they are pushed, with the setup above, the commits are (1)
- only in ``bitbucket.org/yourname/pypy``, and (2) in the branch you
+ even if they are pushed, with the setup above, the commits are only in the
+ branch you
named. Yes, they are publicly visible, but don't worry about someone
- walking around the thousands of repos on bitbucket saying "hah, look
- at the bad coding style of that guy". Try to get into the mindset
+ walking around the many branches of PyPy saying "hah, look
+ at the bad coding style of that person". Try to get into the mindset
that your work is not secret and it's fine that way. We might not
accept it as is for PyPy, asking you instead to improve some things,
- but we are not going to judge you.
+ but we are not going to judge you unless you don't write tests.
Pull Request
------------
@@ -156,25 +170,24 @@
intermediate states, but if you get there, then we're likely to
proceed to the next stage, which is...
-* Get a regular account for pushing directly to
- ``bitbucket.org/pypy/pypy`` (just ask and you'll get it, basically).
+* Get a regular account with developer status for pushing directly to
+ ``foss.heptapod.net/pypy/pypy`` (just ask and you'll get it, basically).
Once you have it you can rewrite your file ``.hg/hgrc`` to contain
- ``default = ssh://hg@bitbucket.org/pypy/pypy``. Your changes will
+ ``default = ssh://hg@foss.heptapod.net/pypy/pypy``. Your changes will
then be pushed directly to the official repo, but (if you follow these
rules) they are still on a branch, and we can still review the
- branches you want to merge.
+ branches you want to merge. With developer status, you can push topic
+ branches. If you wish to push long-lived branches, you will need to ask for
+ higher permissions.
* If you get closer to the regular day-to-day development, you'll notice
that we generally push small changes as one or a few commits directly
- to the branch ``default``. Also, we often collaborate even if we are
- on other branches, which do not really "belong" to anyone. At this
+ to the branch ``default`` or ``py3.6``. Also, we often collaborate even if
+ we are on other branches, which do not really "belong" to anyone. At this
point you'll need ``hg merge`` and learn how to resolve conflicts that
sometimes occur when two people try to push different commits in
parallel on the same branch. But it is likely an issue for later ``:-)``
-.. _bitbucket: https://bitbucket.org/
-
-
Architecture
^^^^^^^^^^^^
@@ -466,7 +479,7 @@
The `example-interpreter`_ repository contains an example interpreter
written using the RPython translation toolchain.
-.. _example-interpreter: https://bitbucket.org/pypy/example-interpreter
+.. _example-interpreter: https://foss.heptapod.net/pypy/example-interpreter
graphviz & pygame for flow graph viewing (highly recommended)
diff --git a/pypy/doc/mercurial_heptapod.rst b/pypy/doc/mercurial_heptapod.rst
new file mode 100644
--- /dev/null
+++ b/pypy/doc/mercurial_heptapod.rst
@@ -0,0 +1,355 @@
+Mercurial and Heptapod short tutorial
+=====================================
+
+.. comment::
+ Taken from https://foss.heptapod.net/fluiddyn/fluiddyn/blob/branch/default/doc/mercurial_heptapod.rst
+ and modified
+
+
+`Mercurial <http://mercurial.selenic.com/>`_ is a free, distributed source
+control management tool. We use it for PyPy, not only because it is written in
+Python, but because its branch model fits our development process better than
+Git's branch model.
+
+Mercurial couples very well with the programs `TortoiseHG
+<https://tortoisehg.bitbucket.io/>`__ and `Meld <https://meldmerge.org/>`__ (if
+you can, just install them, especially Meld).
+
+There are a lot of tutorials and documentations about Mercurial (for example
+`the official Mercurial tutorial
+<http://mercurial.selenic.com/wiki/Tutorial>`_). This page is meant to show you
+what you need to get going with PyPy development.
+
+`Heptapod <https://heptapod.net/>`_ is a friendly fork of GitLab Community
+Edition supporting Mercurial.
+
+Installation
+------------
+
+With TortoiseHG (simple for Windows)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Download the installer from https://tortoisehg.bitbucket.io/.
+(but note you might need the evolve extension)
+
+With conda (cross-platform, recommended for Linux and macOS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On Windows, macOS and Linux, one can use ``conda`` (installed with `miniconda
+<https://docs.conda.io/en/latest/miniconda.html>`__) to install Mercurial with
+few extensions (`hg-evolve <https://pypi.org/project/hg-evolve>`_ and `hg-git
+<http://hg-git.github.io/>`_). On Windows, these commands have to be run in the
+Anaconda Prompt. First, we need to install `conda-app
+<https://pypi.org/project/conda-app>`_ in the base conda environment::
+
+ conda activate base
+ pip install conda-app
+
+Then, with the conda-forge channel added (``conda config --add channels
+conda-forge``), one just needs to run::
+
+ conda-app install mercurial
+
+**Open a new terminal** and the Mercurial command ``hg`` should be available.
+
+.. note ::
+
+ If you don't use TortoiseHG, you should really install the visual diff and
+ merge tool `Meld <https://meldmerge.org/>`__!
+
+Set-up Mercurial
+----------------
+
+You need to create a file ``~/.hgrc``. For a good starting point, you can use
+the command::
+
+ hg config --edit
+
+An example of configuration file::
+
+ [ui]
+ username=myusername <email at adress.org>
+ editor=emacs -nw
+ tweakdefaults = True
+
+ [extensions]
+ hgext.extdiff =
+ # only to use Mercurial with GitHub and Gitlab
+ hggit =
+ # more advanced extensions (really useful for PyPy dev)
+ churn =
+ shelve =
+ rebase =
+ absorb =
+ evolve =
+ topic =
+
+ [extdiff]
+ cmd.meld =
+
+The line starting with hggit is optional and enables the extension `hg-git
+<http://hg-git.github.io/>`_. This extension is useful to work on projects
+using Git, for example hosted on Github and Gitlab.
+
+The extensions churn, shelve, rebase, absorb, evolve and topic are very useful
+for more advanced users. Note that `evolve
+<https://www.mercurial-scm.org/doc/evolution/>`_ and `topic`_
+comes from the package `hg-evolve <https://pypi.org/project/hg-evolve>`_.
+
+.. note ::
+
+ For occasional contribution to PyPy, the evolve and topic extensions have to
+ be installed and activated since we use topic_ branches for short-term
+ development
+
+Get help
+--------
+
+To get help on Mercurial, one can start with::
+
+ hg help
+
+or for a specific command (here ``clone``)::
+
+ hg help clone
+
+Simple workflow
+---------------
+
+To make a copy of an existing repository::
+
+ hg clone https://foss.heptapod.net/pypy/pypy
+
+To get a summary of the working directory state::
+
+ hg summary
+
+or just ``hg sum``.
+
+Before you begin work, open a new topic branch::
+
+ hg topic my_branch
+
+To show changed files in the working directory::
+
+ hg status
+
+or just ``hg st``.
+
+If you add new files or if you deleted files::
+
+ hg add name_of_the_file
+
+ hg remove name_of_the_file
+
+Each time you do some consistent changes::
+
+ hg commit -m "A message explaining the commit"
+
+After a commit command ``hg st`` to check that you did
+what you wanted to do. If you are unhappy with the commit, you can amend it
+with another commit with::
+
+ hg commit --amend
+
+To push the state of your working repository to your repository on the web::
+
+ hg push
+
+The inverse command (pull all commits from the remote repository) is::
+
+ hg pull
+
+Get the last version of a code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First pull all the changesets from the remote repository::
+
+ hg pull
+
+Then update the code to the tip::
+
+ hg update
+
+or just ``hg up``. You can also directly do::
+
+ hg pull -u
+
+Read the history
+^^^^^^^^^^^^^^^^
+
+You can get a list of the changesets with::
+
+ hg log --graph
+
+or just ``hg log -G``. With the ``--graph`` or ``-G`` option, the revisions are
+shown as an ASCII art.
+
+Update the code to an old revision
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``hg up 220`` to update to the revision 220. We can use a tag, bookmark,
+topic name or branch name instead of a number. To get a clean copy, add the
+option ``-C`` (beware).
+
+
+Create a repository from a directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create a new repository in the given directory by doing::
+
+ hg init
+
+Merge-Request based workflow with hg-evolve
+-------------------------------------------
+
+We now use a Merge-Request (MR) based workflow
+
+.. note ::
+
+ GitLab's "merge requests" are equivalent to GitHub's "pull requests".
+
+.. note ::
+
+ In contrast to the standard workflow in Github, Gitlab and Bitbucket, you
+ don't need to fork the repository to create Merge Requests.
+
+Instead, you need to become a "developer" of the project. The developers have
+the permission to push changesets (i.e. "commits") in a topic in the main
+repository (for example https://foss.heptapod.net/pypy/pypy). To
+acquire the "developer" role, please send a message in an issue_ or if needed,
+create a dedicated issue.
+
+.. _issue: https://foss.heptapod.net/pypy/pypy/issues
+
+`Topics <topic>`_ are used in Mercurial for "lightweight branches" (like Git branches).
+The principle is that you first create a topic (with ``hg topic``). Once a
+topic is activated, the changesets created belong to this topic. The new
+changesets gathered in a topic can be pushed in the main repository. Even after
+having been pushed to the main repository, they stay in the ``draft`` phase
+(which means they can be modified, as opposed to ``public`` changesets. Run
+``hg help phases`` for more info).
+
+To list the topics::
+
+ hg topic
+
+To activate a topic already created::
+
+ hg up the_name_of_the_topic
+
+To deactivate the topic and come back to the tip of the default branch::
+
+ hg up default
+
+To get the list of the changesets in the active topic (very useful)::
+
+ hg stack
+
+Developers have to create Merge Requests to get things merged in the targeted
+branch (which is usually default for FluidDyn packages). Let's present an
+example. A developer can do (here, we use ssh but you can also use https)::
+
+ hg clone ssh://hg@foss.heptapod.net/pypy/pypy
+ hg topic fix_something
+ hg commit -m "Fix a bug related to ..."
+ hg push
+
+Mercurial is going to print an URL to create the associated MR. Once created,
+the MR should then be reviewed by a "maintainer". Only maintainers have the
+right to merge a MR, i.e. to publish changesets. The maintainer can tell you
+how to modify your MR and s-he can also directly modify the changesets of the
+MR!
+
+We strongly advice to install and activate the `evolve
+<https://www.mercurial-scm.org/doc/evolution/>`_, rebase and `absorb
+<https://gregoryszorc.com/blog/2018/11/05/absorbing-commit-changes-in-mercurial-4.8/>`_
+extensions locally (see the example of ``.hgrc`` above). This gives a very nice
+user experience for the MRs, with the ability to modify a MR with ``hg absorb``
+and safe history editing.
+
+.. tip ::
+
+ ``hg absorb`` is very useful during code review. Let say that a developer
+ submitted a PR containing few commits. As explained in `this blog post
+ <https://gregoryszorc.com/blog/2018/11/05/absorbing-commit-changes-in-mercurial-4.8/>`_,
+ ``hg absorb`` is a mechanism to automatically and intelligently incorporate
+ uncommitted changes into prior commits. Edit the files to take into account
+ the remarks of the code review and just run::
+
+ hg absorb
+ hg push
+
+ and the PR is updated!
+
+.. tip ::
+
+ If you are asked to "rebase" your MR, it should work with the following commands::
+
+ hg pull
+ hg up name_of_my_topic
+ hg rebase
+ hg push
+
+Working with hggit and Github
+-----------------------------
+
+To clone a git repository::
+
+ hg clone git+ssh://git@github.com/numpy/numpy
+
+or just::
+
+ hg clone https://github.com/numpy/numpy
+
+Git branches are represented as Mercurial bookmarks so such commands can be
+usefull::
+
+ hg log --graph
+
+ hg up master
+
+ hg help bookmarks
+
+ # list the bookmarks
+ hg bookmarks
+
+ # put the bookmark master where you are
+ hg book master
+
+ # deactivate the active bookmark (-i like --inactive)
+ hg book -i
+
+.. note ::
+
+ ``bookmarks``, ``bookmark`` and ``book`` correspond to the same
+ mercurial command.
+
+.. warning ::
+
+ If a bookmark is active, ``hg pull -u`` or ``hg up`` will move the bookmark
+ to the tip of the active branch. You may not want that so it is important to
+ always deactivate an unused bookmark with ``hg book -i`` or with ``hg up
+ master``.
+
+Do not forget to place the bookmark ``master`` as wanted.
+
+Delete a bookmark in a remote repository (close a remote Git branch)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With Mercurial, `we can
+do <https://stackoverflow.com/questions/6825355/how-do-i-delete-a-remote-bookmark-in-mercurial>`_::
+
+ hg bookmark --delete <bookmark name>
+ hg push --bookmark <bookmark name>
+
+Unfortunately, it does not work for a remote Git repository (with hg-git). We
+have to use a Git client, clone the repository with Git and do `something like
+<https://stackoverflow.com/a/10999165/1779806>`_::
+
+ # this deletes the branch locally
+ git branch --delete <branch name>
+ # this deletes the branch in the remote repository
+ git push origin --delete <branch name>
+
+.. _topic: https://www.mercurial-scm.org/doc/evolution/tutorials/topic-tutorial.html
More information about the pypy-commit
mailing list