diff options
Diffstat (limited to 'doc/source/dev')
| -rw-r--r-- | doc/source/dev/gitwash/development_setup.rst | 231 | ||||
| -rw-r--r-- | doc/source/dev/gitwash/forked_page.png | bin | 0 -> 3345 bytes | |||
| -rwxr-xr-x[-rw-r--r--] | doc/source/dev/gitwash/forking_button.png | bin | 13092 -> 8066 bytes | |||
| -rw-r--r-- | doc/source/dev/gitwash/forking_message.png | bin | 0 -> 14880 bytes |
4 files changed, 132 insertions, 99 deletions
diff --git a/doc/source/dev/gitwash/development_setup.rst b/doc/source/dev/gitwash/development_setup.rst index 9027dda64..a7e9c28b9 100644 --- a/doc/source/dev/gitwash/development_setup.rst +++ b/doc/source/dev/gitwash/development_setup.rst @@ -1,145 +1,178 @@ -==================================== -Getting started with Git development -==================================== +.. _development-setup: -This section and the next describe in detail how to set up git for working -with the NumPy source code. If you have git already set up, skip to -:ref:`development-workflow`. +############################################################################## +Setting up git for NumPy development +############################################################################## -Basic Git setup -############### +To contribute code or documentation, you first need -* :ref:`install-git`. -* Introduce yourself to Git:: +#. git installed on your machine +#. a GitHub account +#. a fork of NumPy - git config --global user.email you@yourdomain.example.com - git config --global user.name "Your Name Comes Here" -.. _forking: +****************************************************************************** +Install git +****************************************************************************** + +You may already have git; check by typing ``git --version``. If it's +installed you'll see some variation of ``git version 2.11.0``. +If instead you see ``command is not recognized``, ``command not +found``, etc., +`install git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_. -Making your own copy (fork) of NumPy -#################################### +Then set your name and email: :: -You need to do this only once. The instructions here are very similar -to the instructions at http://help.github.com/forking/ - please see that -page for more detail. We're repeating some of it here just to give the -specifics for the NumPy_ project, and to suggest some default names. + git config --global user.email you@yourdomain.example.com + git config --global user.name "Your Name" .. _set-up-and-configure-a-github-account: -Set up and configure a github_ account -====================================== +****************************************************************************** +Create a GitHub account +****************************************************************************** -If you don't have a github_ account, go to the github_ page, and make one. +If you don't have a GitHub account, visit https://github.com/join to create +one. -You then need to configure your account to allow write access - see the -``Generating SSH keys`` help on `github help`_. +.. _forking: -Create your own forked copy of NumPy_ -========================================= +****************************************************************************** +Create a NumPy fork +****************************************************************************** -#. Log into your github_ account. -#. Go to the NumPy_ github home at `NumPy github`_. -#. Click on the *fork* button: +``Forking`` has two steps -- visit GitHub to create a fork repo in your +account, then make a copy of it on your own machine. - .. image:: forking_button.png +Create the fork repo +============================================================================== - After a short pause, you should find yourself at the home page for - your own forked copy of NumPy_. +#. Log into your GitHub account. +#. Go to the `NumPy GitHub home <https://github.com/numpy/numpy>`_. +#. At the upper right of the page, click ``Fork``: -.. include:: git_links.inc + .. image:: forking_button.png + You'll see -.. _set-up-fork: + .. image:: forking_message.png -Set up your fork -################ + and then you'll be taken to the home page of your forked copy: -First you follow the instructions for :ref:`forking`. + .. image:: forked_page.png -Overview -======== -:: +.. _set-up-fork: - git clone https://github.com/your-user-name/numpy.git - cd numpy - git remote add upstream https://github.com/numpy/numpy.git +Make the local copy +============================================================================== -In detail -========= +#. In the directory where you want the copy created, run :: -Clone your fork ---------------- + git clone https://github.com/your-user-name/numpy.git -#. Clone your fork to the local computer with ``git clone - https://github.com/your-user-name/numpy.git`` -#. Investigate. Change directory to your new repo: ``cd numpy``. Then - ``git branch -a`` to show you all branches. You'll get something - like:: + You'll see something like: :: - * master - remotes/origin/master + $ git clone https://github.com/your-user-name/numpy.git + Cloning into 'numpy'... + remote: Enumerating objects: 12, done. + remote: Counting objects: 100% (12/12), done. + remote: Compressing objects: 100% (12/12), done. + remote: Total 175837 (delta 0), reused 0 (delta 0), pack-reused 175825 + Receiving objects: 100% (175837/175837), 78.16 MiB | 9.87 MiB/s, done. + Resolving deltas: 100% (139317/139317), done. - This tells you that you are currently on the ``master`` branch, and - that you also have a ``remote`` connection to ``origin/master``. - What remote repository is ``remote/origin``? Try ``git remote -v`` to - see the URLs for the remote. They will point to your github_ fork. + A directory ``numpy`` is created on your machine. (If you already have + a numpy directory, GitHub will choose a different name like ``numpy-1``.) + :: - Now you want to connect to the upstream `NumPy github`_ repository, so - you can merge in changes from trunk. + $ ls -l + total 0 + drwxrwxrwx 1 bjn bjn 4096 Jun 20 07:20 numpy .. _linking-to-upstream: -Linking your repository to the upstream repo --------------------------------------------- +#. Give the name ``upstream`` to the main NumPy repo: :: + + cd numpy + git remote add upstream https://github.com/numpy/numpy.git + +#. Set up your repository so ``git pull`` pulls from ``upstream`` by + default: :: + + git config branch.master.remote upstream + git config branch.master.merge refs/heads/master -:: +****************************************************************************** +Look it over +****************************************************************************** - cd numpy - git remote add upstream https://github.com/numpy/numpy.git +#. The branches shown by ``git branch -a`` will include -``upstream`` here is just the arbitrary name we're using to refer to the -main NumPy_ repository at `NumPy github`_. + - the ``master`` branch you just cloned on your own machine + - the ``master`` branch from your fork on GitHub, which git named + ``origin`` by default + - the ``master`` branch on the the main NumPy repo, which you named + ``upstream``. -Just for your own satisfaction, show yourself that you now have a new -'remote', with ``git remote -v show``, giving you something like:: + :: - upstream https://github.com/numpy/numpy.git (fetch) - upstream https://github.com/numpy/numpy.git (push) - origin https://github.com/your-user-name/numpy.git (fetch) - origin https://github.com/your-user-name/numpy.git (push) + master + remotes/origin/master + remotes/upstream/master -To keep in sync with changes in NumPy, you want to set up your repository -so it pulls from ``upstream`` by default. This can be done with:: + If ``upstream`` isn't there, it will be added after you access the + NumPy repo with a command like ``git fetch`` or ``git pull``. - git config branch.master.remote upstream - git config branch.master.merge refs/heads/master -You may also want to have easy access to all pull requests sent to the -NumPy repository:: +#. The repos shown by ``git remote -v show`` will include your fork on GitHub + and the main repo: :: - git config --add remote.upstream.fetch '+refs/pull/*/head:refs/remotes/upstream/pr/*' + upstream https://github.com/numpy/numpy.git (fetch) + upstream https://github.com/numpy/numpy.git (push) + origin https://github.com/your-user-name/numpy.git (fetch) + origin https://github.com/your-user-name/numpy.git (push) -Your config file should now look something like (from -``$ cat .git/config``):: +#. ``git config --list`` will include :: - [core] - repositoryformatversion = 0 - filemode = true - bare = false - logallrefupdates = true - ignorecase = true - precomposeunicode = false - [remote "origin"] - url = https://github.com/your-user-name/numpy.git - fetch = +refs/heads/*:refs/remotes/origin/* - [remote "upstream"] - url = https://github.com/numpy/numpy.git - fetch = +refs/heads/*:refs/remotes/upstream/* - fetch = +refs/pull/*/head:refs/remotes/upstream/pr/* - [branch "master"] - remote = upstream - merge = refs/heads/master + user.email=your_email@example.com + user.name=Your Name + remote.origin.url=git@github.com:your-github-id/numpy.git + remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* + branch.master.remote=upstream + branch.master.merge=refs/heads/master + remote.upstream.url=https://github.com/numpy/numpy.git + remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/* .. include:: git_links.inc + + +****************************************************************************** +Optional: set up SSH keys to avoid passwords +****************************************************************************** + +Cloning your NumPy fork repo required no password, because it read the remote +repo without changing it. Later, though, submitting your pull requests will +write to it, and GitHub will ask for your username and password -- even though +it's your own repo. You can eliminate this authentication without compromising +security by `setting up SSH keys \ +<https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_. + +**If you set up the keys before cloning**, the instructions above change +slightly. Instead of :: + + git clone https://github.com/your-user-name/numpy.git + +run :: + + git clone git@github.com:numpy/numpy.git + +and instead of showing an ``https`` URL, ``git remote -v`` will show :: + + origin git@github.com:your-user-name/numpy.git (fetch) + origin git@github.com:your-user-name/numpy.git (push) + + +**If you have cloned already** and want to start using SSH, see +`Switching remote URLs from HTTPS to SSH \ +<https://help.github.com/en/github/using-git/changing-a-remotes-url#switching-remote-urls-from-https-to-ssh>`_. diff --git a/doc/source/dev/gitwash/forked_page.png b/doc/source/dev/gitwash/forked_page.png Binary files differnew file mode 100644 index 000000000..f369cab3a --- /dev/null +++ b/doc/source/dev/gitwash/forked_page.png diff --git a/doc/source/dev/gitwash/forking_button.png b/doc/source/dev/gitwash/forking_button.png Binary files differindex d0e04134d..9750c0947 100644..100755 --- a/doc/source/dev/gitwash/forking_button.png +++ b/doc/source/dev/gitwash/forking_button.png diff --git a/doc/source/dev/gitwash/forking_message.png b/doc/source/dev/gitwash/forking_message.png Binary files differnew file mode 100644 index 000000000..631296017 --- /dev/null +++ b/doc/source/dev/gitwash/forking_message.png |
