Opened 10 years ago

Closed 9 years ago

Last modified 9 years ago

#14481 closed task (fixed)

document the new workflow

Reported by: R. Andrew Ohana Owned by: Minh Van Nguyen
Priority: major Milestone: sage-6.0
Component: documentation Keywords: sd51
Cc: Robert Bradshaw, Maarten Derickx, David Roe, Jeroen Demeyer, Karl-Dieter Crisman, Keshav Kini, Julian Rüth, Leif Leonhardy, Nathann Cohen, John Palmieri Merged in:
Authors: Volker Braun Reviewers: Marc Mezzarobba
Report Upstream: N/A Work issues:
Branch: u/vbraun/dev_guide (Commits, GitHub, GitLab) Commit: 6582fca9b2e4075cdea11b75bda6d6fc432d329a
Dependencies: Stopgaps:

Status badges

Description (last modified by Volker Braun)

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.

Change History (44)

comment:1 Changed 10 years ago by R. Andrew Ohana

Cc: jrueth added

comment:2 Changed 10 years ago by R. Andrew Ohana

Cc: Julian Rüth added; jrueth removed

comment:3 Changed 10 years ago by R. Andrew Ohana

Milestone: sage-5.10sage-6.0

comment:4 Changed 10 years ago by Leif Leonhardy

Cc: Leif Leonhardy added

comment:5 Changed 10 years ago by Nathann Cohen

Cc: Nathann Cohen added

comment:6 Changed 9 years ago by Maarten Derickx

Cc: Maarten Derickx added

comment:7 Changed 9 years ago by John Palmieri

Cc: John Palmieri added

comment:8 Changed 9 years ago by Volker Braun

(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

comment:9 Changed 9 years ago by R. Andrew Ohana

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.

comment:10 in reply to:  9 Changed 9 years ago by Volker Braun

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.

comment:11 Changed 9 years ago by Volker Braun

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

Last edited 9 years ago by Volker Braun (previous) (diff)

comment:12 Changed 9 years ago by Timo Kluck

Dependencies: #13015
Keywords: sd51 added

Remove circular dependency.

comment:13 Changed 9 years ago by Volker Braun

Branch: u/vbraun/dev_guide

comment:14 Changed 9 years ago by Volker Braun

Authors: Volker Braun
Commit: 67a76032fda3ee140c3bc52422020ef722cbee52
Status: newneeds_review

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


New commits:

67a7603Updated developer manual to document the Sage-git workflow

comment:15 Changed 9 years ago by Nathann Cohen

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

comment:16 Changed 9 years ago by Volker Braun

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.

comment:17 Changed 9 years ago by git

Commit: 67a76032fda3ee140c3bc52422020ef722cbee528663e66b0c5164322a0b552e5997e9d993f19d60

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

8663e66switched tabs to spaces
1489e69fixed long doctest

comment:18 Changed 9 years ago by Nathann Cohen

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

comment:19 Changed 9 years ago by git

Commit: 8663e66b0c5164322a0b552e5997e9d993f19d60ee0a882b1d3e3c3f70a992b2a6b19035b3cc422b

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

ee0a882fix block quoting of git conflict marker
5f50367added missing svg version of figure

comment:20 Changed 9 years ago by Volker Braun

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.

comment:21 Changed 9 years ago by Robert Bradshaw

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

comment:22 Changed 9 years ago by Marc Mezzarobba

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

comment:23 in reply to:  21 Changed 9 years ago by Volker Braun

Description: modified (diff)

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?

comment:24 Changed 9 years ago by Marc Mezzarobba

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.

comment:25 Changed 9 years ago by Volker Braun

Branch: u/vbraun/dev_guideu/mmezzarobba/dev_guide
Commit: ee0a882b1d3e3c3f70a992b2a6b19035b3cc422b3aa6943c2bb248ea85039bb2371bf0902f90fca1

New commits:

3aa6943developer guide: minor rewordings

comment:26 Changed 9 years ago by git

Commit: 3aa6943c2bb248ea85039bb2371bf0902f90fca113c06b71fead7772a7fe754e8af98ea0eae5d7a1

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

13c06b7git dev guide review: update broken links

comment:27 Changed 9 years ago by git

Commit: 13c06b71fead7772a7fe754e8af98ea0eae5d7a17eb90497a4f0d75ca1ec1913badada127e288e16

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

7eb9049dev guide: move git_background after manual_git...
7ed4b2adev guide review: git_background, manual_git, advanced_git

comment:28 Changed 9 years ago by git

Commit: 7eb90497a4f0d75ca1ec1913badada127e288e16f0c78611e175a5aa757bd86ca48f44ae5d232aa5

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

f0c7861git dev guide: add svg version of flowchart.dia

comment:29 Changed 9 years ago by git

Commit: f0c78611e175a5aa757bd86ca48f44ae5d232aa5cfe4d2efd816ccf3dad2c0d6ad4e5229e98959d1

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

cfe4d2egit dev guide review: workflows.rst

comment:30 Changed 9 years ago by Marc Mezzarobba

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.

comment:31 Changed 9 years ago by git

Commit: cfe4d2efd816ccf3dad2c0d6ad4e5229e98959d1a8e2dbe5122a3533225538a80d1102636c86fd2f

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

a8e2dbedev guide: use consistent capitalization in titles

comment:32 Changed 9 years ago by Volker Braun

Branch: u/mmezzarobba/dev_guideu/vbraun/dev_guide
Commit: a8e2dbe5122a3533225538a80d1102636c86fd2fee0a882b1d3e3c3f70a992b2a6b19035b3cc422b

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:

ee0a882fix block quoting of git conflict marker
5f50367added missing svg version of figure

comment:33 in reply to:  32 Changed 9 years ago by Marc Mezzarobba

Branch: u/vbraun/dev_guideu/mmezzarobba/dev_guide
Commit: ee0a882b1d3e3c3f70a992b2a6b19035b3cc422b82e3d2e22e5f7eb880d7ee71a1984b11723de002
Reviewers: Marc Mezzarobba

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:

82e3d2edev guide: use consistent capitalization in titles
d091bf7git dev guide review: workflows.rst
322541fdev guide: move git_background after manual_git...
59921e8dev guide review: git_background, manual_git, advanced_git
219ee2egit dev guide review: update broken links
5d30154developer guide: minor rewordings
ee0a882fix block quoting of git conflict marker
5f50367added missing svg version of figure
8663e66switched tabs to spaces
1489e69fixed long doctest

comment:34 Changed 9 years ago by Volker Braun

Branch: u/mmezzarobba/dev_guideu/vbraun/dev_guide

comment:35 Changed 9 years ago by Volker Braun

Commit: 82e3d2e22e5f7eb880d7ee71a1984b11723de0026582fca9b2e4075cdea11b75bda6d6fc432d329a

I ported Robert's commits over...


New commits:

6582fcaUnneeded Cython setup
a27225aMinor coding_basics tweaks
7547aeeStreamline introduction

comment:36 Changed 9 years ago by Volker Braun

Status: needs_reviewclosed

comment:37 Changed 9 years ago by Nathann Cohen

O_o

Closed ?

Nathann

comment:38 Changed 9 years ago by Volker Braun

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

comment:39 Changed 9 years ago by Nathann Cohen

nonoono it's about the review ? O_o

Nathann

comment:40 Changed 9 years ago by Volker Braun

You had your chance

comment:41 Changed 9 years ago by Nathann Cohen

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

comment:42 Changed 9 years ago by Volker Braun

I reviewed Marc & Roberts changes.

comment:43 Changed 9 years ago by Volker Braun

Resolution: fixed

Script forgot to set "Resolution: fixed"

comment:44 Changed 9 years ago by Jeroen Demeyer

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.

Note: See TracTickets for help on using tickets.