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]

Changed reviewer from Eric Gourgoulhon to Eric Gourgoulhon, Tobias Diez

[mkoeppe]

Description changed:

--- 
+++ 
@@ -2,15 +2,8 @@

 the documentation at ​https://doc.sagemath.org/html/en/developer/walk_through.html is not really reflecting some of the recent changes to the readme

-Also the reviewer's checklist https://doc.sagemath.org/html/en/developer/reviewer_checklist.html
-should be updated using material from https://wiki.sagemath.org/ReviewChecklist  and that wiki page replaced by a link to the manual.
-
 `make` takes very long. Could add discussion of `make build`
-
-It could also explain when make ends in  Error building Sage, what to do next

 Also git instructions need updating as discussed in https://groups.google.com/g/sage-devel/c/e9Nt_E4glkM/m/Lpmz_va_BAAJ

-Also should explain `configure --enable-editable` (https://wiki.sagemath.org/ReleaseTours/sage-9.3#Editable_.28.22in-place.22.2C_.22develop.22.29_installs_of_the_Sage_library)

-

[mkoeppe]

comment:47

Reduced the ticket description. Follow-up in #33088.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 08e3da4 to 2e2b3fc

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

2e2b3fc

src/doc/en/developer/walk_through.rst: Also refer to README.md

[mkoeppe]

comment:49

Replying to @tobiasdiez:

I find a short (but up-to-date) installation instructions helpful for newcomers. It adds quite a barrier if you need to read 5 pages just to get started with compilation.

OK, I have changed it now to point primarily to the instructions in README.md; I think this goes into the direction that you have in mind

[tobiasdiez]

comment:50

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

[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_sectionsage_development_processin_developer_s_guide to u/slelievre/29784

[slel]

Changed commit from 2e2b3fc to cbd5953

[slel]

Description changed:

--- 
+++ 
@@ -1,9 +1,17 @@
 (from #29733)

-the documentation at ​https://doc.sagemath.org/html/en/developer/walk_through.html is not really reflecting some of the recent changes to the readme
+Let the documentation, in particular
+the developer walk-through at

-`make` takes very long. Could add discussion of `make build`
+- https://doc.sagemath.org/html/en/developer/walk_through.html

-Also git instructions need updating as discussed in https://groups.google.com/g/sage-devel/c/e9Nt_E4glkM/m/Lpmz_va_BAAJ
+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
+

[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*/
-

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

c6e23bb

29786: README.md: Fix and

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from cbd5953 to c6e23bb

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

9615517

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

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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).

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

d04d123

29784: README.md: Remove extra blank lines

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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