Update section "Sage Development Process" in Developer's Guide

[mkoeppe]

(from #29733)

Let the documentation, in particular
the developer walk-through at

• https://doc.sagemath.org/html/en/developer/walk_through.html

better reflect recent changes to the readme.

Mention that make takes very long.

Add discussion of make build.

Update Git instructions as discussed in

• https://groups.google.com/g/sage-devel/c/e9Nt_E4glkM/m/Lpmz_va_BAAJ

CC: @tobiasdiez @dimpase @jhpalmieri @slel @yuan-zhou @DavidAyotte @nbruin @egourgoulhon

Component: documentation

Author: Matthias Koeppe

Branch/Commit: d04d123

Reviewer: Eric Gourgoulhon, Tobias Diez, Samuel Lelièvre

Issue created by migration from https://trac.sagemath.org/ticket/29784

[tobiasdiez]

comment:1

It might be also helpful to add the steps from #25206 comment:63 to the documentation.

[mkoeppe]

comment:2

Indeed. Are you planning to work on this?

[mkoeppe]

comment:7

Moving to 9.4, as 9.3 has been released.

[mkoeppe]

Branch: u/mkoeppe/update_section__sage_development_process__in_developer_s_guide

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

831e3a7	src/doc/en/developer/walk_through.rst: Remove duplicated (incomplete) build instructions
4c1d1f4	src/doc/en/developer/walk_through.rst: Switch from 'make' to 'make build' for rebuilds

[sagetrac-git]

Commit: 4c1d1f4

[mkoeppe]

Author: Matthias Koeppe

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

7f00cbf	README.md: Fix typo
5200907	README.md: Remove link to 'Sage virtual appliance'

[sagetrac-git]

Changed commit from 4c1d1f4 to 5200907

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

ff4d378

README.md, src/doc/en/installation/source.rst: Reduce duplication of installation steps

[sagetrac-git]

Changed commit from 5200907 to ff4d378

[egourgoulhon]

comment:17

Thanks for the update!

Maybe in README.md, replace

12. Type `make`.  That's it! Everything is automatic and
   non-interactive; but it will take a few hours (on a recent
   computer).

by something like

12. Type `make`.  That's it! Everything is automatic and
   non-interactive. NB: you can shorten the build time by typing instead 
   `MAKE='make -jNUM' make`, thereby telling the `make` program to run `NUM` jobs 
   in parallel. A recommended value for `NUM` is twice the number of cores of 
   your CPU. With `NUM` = 8, building Sage takes less than one hour on a modern 
   computer. 

[dimpase]

comment:18

With NUM = 8, building Sage takes less than one hour on a modern

computer. `

This is only true if many packages come from the system. Of course building gcc takes more time...

[slel]

comment:51

Thanks for these welcome changes.

Some lines are indented 3 spaces, maybe use 4 throughout?

Suggested shorter rephrasing:

-    * Compilers: `gcc`, `gfortran`, `g++` (a matching set of these
-      three will avoid the compilation of Sage-specific compilers -
-      unless they are too old).  See the Installation Manual for a
-      discussion of suitable compilers.
+    * Compilers: `gcc`, `gfortran`, `g++` (a recent enough matching
+      set of these three will avoid building Sage-specific compilers).
+      See the Installation Manual for a discussion of suitable compilers.

Positive review from me with or without these changes.

[slel]

Changed reviewer from Eric Gourgoulhon, Tobias Diez to Eric Gourgoulhon, Tobias Diez, Samuel Lelièvre

[mkoeppe]

comment:52

OK if you want to push this change to the ticket.

[egourgoulhon]

comment:53

Replying to @tobiasdiez:

That's a very good idea, I like it!

So do I.

[slel]

comment:54

Here are some changes to the README
(all in a single commit, sorry).

As listed in the commit message:

• Adjust indentation
• Merge steps 2 and 3 for consistency since the Git version
  of step 2 already changed into the Sage directory
• Minor rephrasing, e.g.:
  • "to something not containing any non-alphanumeric characters"
    -> "to contain only alphanumeric characters"
  • "(a matching set of these three will avoid the compilation
    of Sage-specific compilers - unless they are too old)" ->
    "(a recent enough matching set of these three will avoid
    building Sage-specific compilers)."
• Update required disk space to "at least 10 GB" (rather than 6)
• Spell out some abbreviations (OSS license -> software license;
  NFS -> network file system; cd -> change directory)
• Add --tags to git clone
• Fix minor punctuation inconsistencies (use - for all lists
  instead of sometimes *, comma after opensuse, period after bc)
• Expand the "try it out" item to suggest some things to try
• Suggest bookmarking the local documentation in your browser
• Add link to online list of Sage packages
• Add optional step to add symlink to sage in /usr/local/bin

---

New commits:

cbd5953

29784: README.md: Fix indentation, minor updates

[slel]

Changed branch from u/mkoeppe/update_section__sage_development_process__in_developer_s_guide to u/slelievre/29784

[slel]

Changed commit from 2e2b3fc to cbd5953

[mkoeppe]

comment:55

            $ ORIG=https://github.com/sagemath/sage.git
-            $ git clone -c core.symlinks=true --branch master $ORIG
+            $ git clone -c core.symlinks=true --branch --tags develop $ORIG

The command with this change does not work. "develop" must come right after "--branch"

[mkoeppe]

comment:56

And removing this breaks the workflow in the case of git

-3. `cd` into the source/build directory:
-
-        $ cd sage*/
-

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

c6e23bb

29786: README.md: Fix and

[sagetrac-git]

Changed commit from cbd5953 to c6e23bb

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

9615517

29784: README.md: Fix `--tags` and `cd`

[sagetrac-git]

Changed commit from c6e23bb to 9615517

[slel]

comment:60

Better like this?

[mkoeppe]

comment:61

Yes, looking good, thanks

[egourgoulhon]

comment:62

Could you please remove this spurious empty line in README.md:

             $ cd sage-x.y/  # adapt x.y
 
-
     - [Git] Alternatively, clone the Sage git repository:
 
             $ ORIG=https://github.com/sagemath/sage.git

It causes bad formatting in some markdown readers (e.g. abricotine).

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

d04d123

29784: README.md: Remove extra blank lines

[sagetrac-git]

Changed commit from 9615517 to d04d123

[egourgoulhon]

comment:64

Thanks!

[mkoeppe]

comment:65

Thanks everyone for review and edits!

[vbraun]

Changed branch from u/slelievre/29784 to d04d123