Use "git trac" in the developer guide

[vbraun]

Component: documentation

Author: Volker Braun, Karl-Dieter Crisman

Branch/Commit: 9b04b3f

Reviewer: Ralf Stephan, Volker Braun, Karl-Dieter Crisman

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

[83660e46-0051-498b-a8c1-f7a7bd232b5a]

comment:44

Replying to @kcrisman:

I just hate that someone is directed first to install something else in order to even start thinking of developing Sage. :-(

And it's IMHO a bit weird to assume someone would start developing Sage without (ever?) having it installed...

Well, what I meant was installing something that isn't Sage itself, sorry if that wasn't clear.

Oh, I was referring to the draft:

"Obviously you need the Sage source code to develop, so we download it from github which is a public read-only mirror (=faster) of our internal git repository [...]"

Or, how I read it:

"Obviously you need the Sage source code to develop, so we download it from github [WTF?!] which is a public read-only mirror [Aha, so I previously installed the wrong version?] (=faster) [Ok.] of our internal [!?!?!] git repository [...]"

Sorry for my words being misleading... :-/

P.S.: A mirror is always "read-only". (Otherwise it would be a proxy, or an instance of a distributed system.)

[vbraun]

comment:45

Well you can always suggest a better wording ;-) IMHO its clear that we = the manual author and reader, and "internal" = the Sage project's.

[83660e46-0051-498b-a8c1-f7a7bd232b5a]

comment:46

Replying to @vbraun:

Well you can always suggest a better wording ;-) IMHO its clear that we = the manual author and reader, and "internal" = the Sage project's.

Hmmm, I'd somehow mention that by doing so he/she/we/one obtain(s) both the latest stable (aka "official") release [= master branch] as well as the current/latest development __release__ [= develop branch, which corresponds to the latest beta/rc version]; each of those branches corresponds to its respective source tarball (he/she/we/one might have downloaded already before getting involved into Sage development, or before reading this).

(And here we use the github mirror just for speed reasons; it only mirrors a subset of what's on git.sagemath.org, namely only those two branches [one starts with], while the latter has everything, including branches (~= tickets) not yet merged, and therefore one will use the primary repository -- git.sagemath.org -- for developing = working on tickets.)

[kcrisman]

comment:47

I'll make some changes along these lines in what I'm working on now. I got a lot done earlier in the afternoon and am now going through things to make sure I didn't miss anything. I should push something within an hour.

Leif, I see what you were referring to - not my comment, but Volker's (? or someone else?) wording in the document itself. I was referring to needing to install git-trac to work easily with Sage. But this comment is well-taken and easy to deal with. I don't think that all the detail you mention is necessary at that particular location but it's worth alluding to, anyway.

[kcrisman]

comment:48

I'll make some changes along these lines in what I'm working on now. I got a lot done earlier in the afternoon and am now going through things to make sure I didn't miss anything. I should push something within an hour.

Okay, two hours... but seriously coming soon.

[kcrisman]

Changed branch from u/vbraun/use__git_trac__in_the_developer_guide to u/kcrisman/ticket/16030

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

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

50e89bf

Significant reconfiguration and some rewrite of developer guide.

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

Changed commit from e3259d0 to 50e89bf

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

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

e5ebea6

Add info about sage -dev -h to the developer guide.

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

Changed commit from 50e89bf to e5ebea6

[kcrisman]

comment:52

Okay, I think I caught all links and so forth. This makes me happy enough, thank you very much for the opportunity to work on this before merging.

Just FYI, I don't think there is really anything that wrong with the dev scripts (though I don't doubt there are bugs of some kind), but I have to admit that they are under documented - see my last commit, and #15558.

[kcrisman]

comment:53

Another thing I just thought of - we should probably mention somewhere close to the beginning that you won't be able to do much with your changes (except in .py files, maybe?) unless you have the compiler prereqs... is there an obvious place in the developer guide itself to link to regarding this? (We could link to the installation guide but I don't know how easy that is with our current document structure.)

[vbraun]

comment:54

It should be clear that you won't get very far if you can't compile Sage. The "Rebuilding Sage" section already links to the install guide.

I disagree with you presenting "sage -dev" as an equal alternative. Having two competing ways to achieve the same thing is a shitty UI. People read the manual because they want to know what is recommended, not what one could also do but later learns that most developers don't do. PEP 20: "There should be one-- and preferably only one --obvious way to do it."

[kcrisman]

comment:55

It should be clear that you won't get very far if you can't compile Sage.

Well, it might not be to someone who has never heard the word "compile" before. Such people should still be able to try out things like adding doctests or examples.

The "Rebuilding Sage" section already links to the install guide.

Nope, turns out it was missing http:// - I'll fix that in a jiffy now.

I disagree with you presenting "sage -dev" as an equal alternative. Having two competing ways to achieve the same thing is a shitty UI. People read the manual because they want to know what is recommended, not what one could also do but later learns that most developers don't do. PEP 20: "There should be one-- and preferably only one --obvious way to do it."

I don't know that I always agree with PEP 20. There are benefits - mathematically, for sure - in having more than one way to do things. I would argue this is also true in computer things - I like that I can either double-click on a folder OR use the Terminal to "open" it; depending on context, they are both useful options. In fact, this is why many people like Perl, right? Sometimes it's just personality or preference, though I do prefer the Python way on this most of the time. But it shouldn't be a dogma.

Anyway, it's not worth discussing at length here; I know you feel this way about it (see discussion above). I was just trying to soften the language while still presenting git trac as the preferred option. I don't feel like I changed the wording to have it be an equal alternative, but I'm open to suggestions while still presenting sage -dev as a possible option for those who looking for it.

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

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

d4bf77a

Fixed hyperlinks and added minor information about compiling Sage

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

Changed commit from e5ebea6 to d4bf77a

[vbraun]

comment:57

Replying to @kcrisman:

In fact, this is why many people like Perl, right?

That is what makes Perl so unusable for large projects. Code written by two different people generally looks like it was written in completely different languages ;)

[vbraun]

Changed branch from u/kcrisman/ticket/16030 to u/vbraun/ticket/16030

[vbraun]

comment:59

I've added a note to spell out what is recommended.

---

New commits:

fd91197

be clear about what is recommended

[vbraun]

Changed commit from d4bf77a to fd91197

[vbraun]

Changed reviewer from Ralf Stephan to Ralf Stephan, Volker Braun

[vbraun]

Changed author from Volker Braun to Volker Braun, Karl-Dieter Crisman

[kcrisman]

Changed reviewer from Ralf Stephan, Volker Braun to Ralf Stephan, Volker Braun, Karl-Dieter Crisman

[kcrisman]

comment:61

I don't know about that sickly green ;-) is that an official Sage color? (Is it sage?) But I don't think we'll probably come up with a better compromise than this, so as long as the design folks don't complain I'll say this is okay.

I don't want to give final positive review because I did so some rearranging and want someone to confirm it builds the doc properly, but it all seems fine on my end so that's all that remains, since I definitely went over everything else pretty carefully.

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

Changed commit from fd91197 to 9b04b3f

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

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

9b04b3f

remove tabs

[vbraun]

Changed branch from u/vbraun/ticket/16030 to 9b04b3f