document the new workflow

[ohanar]

The new git based workflow has been more or less figured out, now it just needs to be documented.

Do NOT use ​​https://github.com/sagemath/sage-developer-git for new commits, any changes must go into the branch that is attached to this ticket.

[vbraun]

(repost from sage-git)

I started some work on the new developer guide covering the git workflow. I created a repository at ​https://github.com/vbraun/sage-developer-git with a self-contained copy of the docbuild steps, so you can make changes without an extra Sage tree. Once this is in good shape, I'm planning to replace the current developer guide with it. If you want to help let me know and I'll add you to the collaborators. I think this is the quickest way to get off the ground while having all of the usual sphinx extensions at our disposal.

The result is also served as github page at ​http://vbraun.github.io/sage-developer-git

[ohanar]

If we want to transfer it to the sagemath account, there is already a group set up with most of the people who have contributed to the git transition.

[vbraun]

Replying to ohanar:

If we want to transfer it to the sagemath account, there is already a group set up with most of the people who have contributed to the git transition.

I'd be happy to, but I don't have sufficient permissions to transfer ownership to (or create repos in) the sagemath github org.

[vbraun]

I moved the repo to the sagemath org and added the sage-git group to the collaborators

Repository: ​https://github.com/sagemath/git-developer-guide Current version of the developer guide: ​http://sagemath.github.io/git-developer-guide/

[tkluck]

Remove circular dependency.

[vbraun]

The branch is identical to ​http://sagemath.github.io/git-developer-guide if that helps to review it...

---

New commits:

​67a7603

Updated developer manual to document the Sage-git workflow

[ncohen]

Could you split that into thematic changes ? It looks that you write a lot of doc, but you also move some, and you also fix semicolumns, and you also fix typoes, and you also fix doctests... O_o

Nathann

[vbraun]

You can see the individual commits here: ​https://github.com/vbraun/sage-developer-git. I don't think that'll make it easier to follow, though. I also don't think that we need a lot of discussion here, this is just documenting what we have. There can't be any questions of mathematical correctness. If your English is better than mine then please go ahead and make the docs easier to understand, but in a future ticket.

[git]

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

​8663e66	switched tabs to spaces
​1489e69	fixed long doctest

[ncohen]

YOooooooo Volker !

I would like to review the new doc, but this is really too large. It would really help if you could split that for each section or something like that, for keeping trac of everything that happens in ​@67a7603 without any explanation is scary O_o

By the way, there are some warnings when I build the developper's doc with.

Nathann

[git]

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

​ee0a882	fix block quoting of git conflict marker
​5f50367	added missing svg version of figure

[vbraun]

I've fixed the warnings.

I moved sections around to have a coherent document, so it can't be "split into sections". Just read one section at a time. If you want to know how a single file changed then just run, e.g., git diff master HEAD doctesting.rst.

[robertwb]

I just reviewed "General Conventions" and started on "Cython" but it feels like there's nothing new there. What sections are new that actually need to be reviewed (other than vetting the new general layout, which looks fine to me so far, though I think the table of contents is a bit deep on the landing page).

​https://github.com/sagemath/git-developer-guide/pull/2

[mmezzarobba]

A minor note on walk_through.rst: sage -dev pull is used (as part of "going through the above steps") before being introduced.

[vbraun]

Replying to robertwb:

What sections are new that actually need to be reviewed (other than vetting the new general layout, which looks fine to me so far, though I think the table of contents is a bit deep on the landing page).

• In the "Writing Code for Sage" chapter the only thing that is really new are the packaging sections. I removed all mercurial stuff and references to the old file system layout, of course.

• The "Sage Notebook Developer Guide" is unchanged except that I moved general tips&tricks for using git (not specific to the notebook) elsewhere.

The rest is new.

​https://github.com/sagemath/git-developer-guide/pull/2

The github repo is old, current work is done on the branch on this ticket. Can you rebase your patches?

[mmezzarobba]

I've reviewed the first three chapters (not including possible English language issues, given my English level!) and pushed a patch with minor changes to u/mmezzarobba/dev_guide. These are only suggestions, I leave it to you to merge them or not.

I agree with Volker's comment that we should get this merged as soon as possible and keep improvements to future tickets.

[vbraun]

New commits:

​3aa6943

developer guide: minor rewordings

[git]

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

​13c06b7

git dev guide review: update broken links

[git]

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

​7eb9049	dev guide: move git_background after manual_git...
​7ed4b2a	dev guide review: git_background, manual_git, advanced_git

[git]

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

​f0c7861

git dev guide: add svg version of flowchart.dia

[git]

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

​cfe4d2e

git dev guide review: workflows.rst

[mmezzarobba]

I just finished a quick review of the "Git and Sage Development" part. Please cherry-pick those of my commits you judge relevant!

On a different note, and somewhat ironically, there are test failures in doctesting.rst.

[git]

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

​a8e2dbe

dev guide: use consistent capitalization in titles

[vbraun]

There was already a checked-in svg version and the doctests fixed, see comment:19. You should rebase your branch onto the latest version of mine.

---

New commits:

​ee0a882	fix block quoting of git conflict marker
​5f50367	added missing svg version of figure

[mmezzarobba]

Replying to vbraun:

There was already a checked-in svg version and the doctests fixed, see comment:19.

I missed these commits, sorry.

You should rebase your branch onto the latest version of mine.

Done.

---

Last 10 new commits:

​82e3d2e	dev guide: use consistent capitalization in titles
​d091bf7	git dev guide review: workflows.rst
​322541f	dev guide: move git_background after manual_git...
​59921e8	dev guide review: git_background, manual_git, advanced_git
​219ee2e	git dev guide review: update broken links
​5d30154	developer guide: minor rewordings
​ee0a882	fix block quoting of git conflict marker
​5f50367	added missing svg version of figure
​8663e66	switched tabs to spaces
​1489e69	fixed long doctest

[vbraun]

I ported Robert's commits over...

---

New commits:

​6582fca	Unneeded Cython setup
​a27225a	Minor coding_basics tweaks
​7547aee	Streamline introduction

[ncohen]

O_o

Closed ?

Nathann

[vbraun]

Open a new ticket if you want to make any further changes.

[ncohen]

nonoono it's about the review ? O_o

Nathann

[vbraun]

You had your chance

[ncohen]

That's not my point. What is going on with this ticket ? Has it been reviewed ? Do you merge it ? I mean, I don't get it O_o

Nathann

[vbraun]

I reviewed Marc & Roberts changes.

[vbraun]

Script forgot to set "Resolution: fixed"

[jdemeyer]

Commit 67a76032fda3ee140c3bc52422020ef722cbee52 on this ticket reverted the documentation changes introduced by #13311. You might want to investigate what happened, I hope that there aren't a lot of tickets from Sage 5.13 which are accidentally reverted in Sage 6.0.