8000 DOC: devguide cleanup: remove Gitwash and too verbose Git details · numpy/numpy@8e1def7 · GitHub
[go: up one dir, main page]

Skip to content

Commit 8e1def7

Browse files
committed
DOC: devguide cleanup: remove Gitwash and too verbose Git details
Also clean up some outdated info on the CI setup and wheel builds. This is a very straightforward PR, and already pre-discussed in the community meeting 2 weeks ago. This change does not yet fix the more structural issues with this developer guide, like it being quite hard to navigate. Next step is to update all the doc build info, and after that the devguide requires more surgery. [skip azp] [skip actions] [skip cirrus]
1 parent c9340c2 commit 8e1def7

15 files changed

+41
-626
lines changed

doc/source/dev/development_workflow.rst

Lines changed: 37 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,10 @@
44
Development workflow
55
====================
66

7-
You already have your own forked copy of the NumPy_ repository, by
8-
following :ref:`forking`, :ref:`set-up-fork`, you have configured git_
9-
by following :ref:`configure-git`, and have linked the upstream
10-
repository as explained in :ref:`linking-to-upstream`.
11-
12-
What is described below is a recommended workflow with Git.
7+
You already have your own forked copy of the NumPy repository, have configured
8+
Git, and have linked the upstream repository as explained in
9+
:ref:`linking-to-upstream`. What is described below is a recommended workflow
10+
with Git.
1311

1412
Basic workflow
1513
##############
@@ -32,12 +30,6 @@ In short:
3230
This way of working helps to keep work well organized and the history
3331
as clear as possible.
3432

35-
.. seealso::
36-
37-
There are many online tutorials to help you `learn git`_. For discussions
38-
of specific git workflows, see these discussions on `linux git workflow`_,
39-
and `ipython git workflow`_.
40-
4133
.. _making-a-new-feature-branch:
4234

4335
Making a new feature branch
@@ -79,8 +71,8 @@ In more detail
7971
#. Make some changes. When you feel that you've made a complete, working set
8072
of related changes, move on to the next steps.
8173

82-
#. Optional: Check which files have changed with ``git status`` (see `git
83-
status`_). You'll see a listing like this one::
74+
#. Optional: Check which files have changed with ``git status``. You'll see a
75+
listing like this one::
8476

8577
# On branch my-new-feature
8678
# Changed but not updated:
@@ -96,11 +88,11 @@ In more detail
9688
no changes added to commit (use "git add" and/or "git commit -a")
9789

9890
#. Optional: Compare the changes with the previous version using with ``git
99-
diff`` (`git diff`_). This brings up a simple text browser interface that
91+
diff``. This brings up a simple text browser interface that
10092
highlights the difference between your files and the previous version.
10193

102-
#. Add any relevant modified or new files using ``git add modified_file``
103-
(see `git add`_). This puts the files into a staging area, which is a queue
94+
#. Add any relevant modified or new files using ``git add modified_file``.
95+
This puts the files into a staging area, which is a queue
10496
of files that will be added to your next commit. Only add files that have
10597
related, complete changes. Leave files with unfinished changes for later
10698
commits.
@@ -118,26 +110,23 @@ In more detail
118110
-a``. The extra ``-a`` flag automatically commits all modified files and
119111
removes all deleted files. This can save you some typing of numerous ``git
120112
add`` commands; however, it can add unwanted changes to a commit if you're
121-
not careful. For more information, see the helpful use-case description in
122-
the `tangled working copy problem`_.
113+
not careful.
123114

124-
#. Push the changes to your forked repo on github_::
115+
#. Push the changes to your fork on GitHub::
125116

126117
git push origin my-new-feature
127118

128-
For more information, see `git push`_.
129-
130119
.. note::
131120

132121
Assuming you have followed the instructions in these pages, git will create
133-
a default link to your github_ repo called ``origin``. In git >= 1.7 you
122+
a default link to your GitHb repo called ``origin``. You
134123
can ensure that the link to origin is permanently set by using the
135124
``--set-upstream`` option::
136125

137126
git push --set-upstream origin my-new-feature
138127

139-
From now on git_ will know that ``my-new-feature`` is related to the
140-
``my-new-feature`` branch in your own github_ repo. Subsequent push calls
128+
From now on, ``git`` will know that ``my-new-feature`` is related to the
129+
``my-new-feature`` branch in your own GitHub repo. Subsequent push calls
141130
are then simplified to the following::
142131

143132
git push
@@ -212,12 +201,6 @@ these fragments in each commit message of a PR:
212201
settings.
213202
`See the configuration files for these checks. <https://github.com/numpy/numpy/tree/main/.github/workflows>`__
214203

215-
* ``[skip travis]``: skip TravisCI jobs
216-
217-
`TravisCI <https://www.travis-ci.com/>`__ will test your changes against
218-
Python 3.9 on the PowerPC and s390x architectures.
219-
`See the configuration file for these checks. <https://github.com/numpy/numpy/blob/main/.travis.yml>`__
220-
221204
* ``[skip azp]``: skip Azure jobs
222205

223206
`Azure <https://azure.microsoft.com/en-us/products/devops/pipelines>`__ is
@@ -248,47 +231,42 @@ in order to build wheels through continuous integration services. To save resour
248231
cibuildwheel wheel builders are not run by default on every single PR or commit to main.
249232

250233
If you would like to test that your pull request do not break the wheel builders,
251-
you may either append ``[wheel build]`` to the end of the commit message of the commit
252-
or add one of the following labels to the pull request(if you have the permissions to do so):
253-
254-
- ``36 - Build``: for pull requests changing build processes/configurations
255-
- ``03 - Maintenance``: for pull requests upgrading dependencies
256-
- ``14 - Release``: for pull requests preparing for a release
257-
258-
The wheels built via github actions (including 64-bit linux, macOS, and
259-
windows, arm64 macOS, and 32-bit windows) will be uploaded as artifacts in zip
260-
files. You can access them from the Summary page of the "Wheel builder"
261-
Action_. The aarch64 wheels built via travis_ CI are not available as artifacts.
234+
you can do so by appending ``[wheel build]`` to the first line of the commit
235+
message of the newest commit in your PR. Please only do so for build-related
236+
PRs, because running all wheel builds is slow and expensive.
237+
238+
The wheels built via github actions (including 64-bit Linux, x86-64 macOS, and
239+
32/64-bit Windows) will be uploaded as artifacts in zip files. You can access
240+
them from the Summary page of the "Wheel builder" action. The aarch64 Linux and
241+
arm64 macOS wheels built via Cirrus CI are not available as artifacts.
262242
Additionally, the wheels will be uploaded to
263243
https://anaconda.org/scientific-python-nightly-wheels/ on the following conditions:
264244

265245
- by a weekly cron job or
266-
- if the github action or travis build has been manually triggered, which requires appropriate permissions
246+
- if the GitHub Actions or Cirrus build has been manually triggered, which
247+
requires appropriate permissions
267248

268249
The wheels will be uploaded to https://anaconda.org/multibuild-wheels-staging/
269250
if the build was triggered by a tag to the repo that begins with ``v``
270251

271-
.. _Action: https://github.com/numpy/numpy/actions
272-
.. _travis: https://app.travis-ci.com/github/numpy/numpy/builds
273252

274253
.. _workflow_mailing_list:
275254

276255
Get the mailing list's opinion
277-
=======================================================
256+
==============================
278257

279258
If you plan a new feature or API change, it's wisest to first email the
280259
NumPy `mailing list <https://mail.python.org/mailman/listinfo/numpy-discussion>`_
281260
asking for comment. If you haven't heard back in a week, it's
282261
OK to ping the list again.
283262

263+
284264
.. _asking-for-merging:
285265

286266
Asking for your changes to be merged with the main repo
287267
=======================================================
288268

289-
When you feel your work is finished, you can create a pull request (PR). Github
290-
has a nice help page that outlines the process for `filing pull requests`_.
291-
269+
When you feel your work is finished, you can create a pull request (PR).
292270
If your changes involve modifications to the API or addition/modification of a
293271
function, add a release note to the ``doc/release/upcoming_changes/``
294272
directory, following the instructions and format in the
@@ -308,14 +286,13 @@ If your PR is large or complicated, asking for input on the numpy-discussion
308286
mailing list may also be useful.
309287

310288

311-
312289
.. _rebasing-on-main:
313290

314291
Rebasing on main
315292
================
316293

317-
This updates your feature branch with changes from the upstream `NumPy
318-
github`_ repo. If you do not absolutely need to do this, try to avoid doing
294+
This updates your feature branch with changes from the upstream NumPy
295+
GitHub repo. If you do not absolutely need to do this, try to avoid doing
319296
it, except perhaps when you are finished. The first step will be to update
320297
the remote repository with new commits from upstream::
321298

@@ -376,8 +353,7 @@ If you forgot to make a backup branch::
376353
git reset --hard my-feature-branch@{2}
377354

378355
If you didn't actually mess up but there are merge conflicts, you need to
379-
resolve those. This can be one of the trickier things to get right. For a
380-
good description of how to do this, see `this article on merging conflicts`_.
356+
resolve those.
381357

382358

383359
Additional things you might want to do
@@ -470,8 +446,8 @@ and the history looks now like this::
470446
If it went wrong, recovery is again possible as explained :ref:`above
471447
<recovering-from-mess-up>`.
472448

473-
Deleting a branch on github_
474-
============================
449+
Deleting a branch on GitHub
450+
===========================
475451

476452
::
477453

@@ -490,7 +466,7 @@ Several people sharing a single repository
490466

491467
If you want to work on some stuff with other people, where you are all
492468
committing into the same repository, or even the same branch, then just
493-
share it via github_.
469+
share it via GitHub.
494470

495471
First fork NumPy into your account, as from :ref:`forking`.
496472

@@ -549,14 +525,12 @@ To see a linear list of commits for this branch::
549525

550526
git log
551527

552-
You can also look at the `network graph visualizer`_ for your github_
553-
repo.
554528

555529
Backporting
556530
===========
557531

558-
Backporting is the process of copying new feature/fixes committed in
559-
`numpy/main`_ back to stable release branches. To do this you make a branch
532+
Backporting is the process of copying new feature/fixes committed in NumPy's
533+
``main`` branch back to stable release branches. To do this you make a branch
560534
off the branch you are backporting to, cherry pick the commits you want from
561535
``numpy/main``, and then submit a pull request for the branch containing the
562536
backport.
@@ -569,7 +543,7 @@ backport.
569543
git checkout -b backport-3324 upstream/maintenance/1.8.x
570544

571545
2. Now you need to apply the changes from main to this branch using
572-
`git cherry-pick`_::
546+
``git cherry-pick``::
573547

574548
# Update remote
575549
git fetch upstream
@@ -585,7 +559,7 @@ backport.
585559

586560
3. You might run into some conflicts cherry picking here. These are
587561
resolved the same way as merge/rebase conflicts. Except here you can
588-
use `git blame`_ to see the difference between main and the
562+
use ``git blame`` to see the difference between main and the
589563
backported branch to make sure nothing gets screwed up.
590564

591565
4. Push the new branch to your Github repository::
@@ -636,5 +610,3 @@ them to ``upstream`` as follows:
636610
first that you're about to push the changes you want to the place you
637611
want.
638612

639-
640-
.. include:: gitwash/git_links.inc

doc/source/dev/gitwash/configure_git.rst

Lines changed: 0 additions & 123 deletions
This file was deleted.

0 commit comments

Comments
 (0)
0