Opened 6 years ago

Closed 5 years ago

Last modified 5 years ago

#14481 closed task (fixed)

document the new workflow

Reported by: ohanar Owned by: mvngu
Priority: major Milestone: sage-6.0
Component: documentation Keywords: sd51
Cc: robertwb, mderickx, roed, jdemeyer, kcrisman, kini, saraedum, leif, ncohen, jhpalmieri Merged in:
Authors: Volker Braun Reviewers: Marc Mezzarobba
Report Upstream: N/A Work issues:
Branch: u/vbraun/dev_guide (Commits) Commit: 6582fca9b2e4075cdea11b75bda6d6fc432d329a
Dependencies: Stopgaps:

Description (last modified by vbraun)

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 6 years ago by ohanar

  • Cc jrueth added

comment:2 Changed 6 years ago by ohanar

  • Cc saraedum added; jrueth removed

comment:3 Changed 6 years ago by ohanar

  • Milestone changed from sage-5.10 to sage-6.0

comment:4 Changed 6 years ago by leif

  • Cc leif added

comment:5 Changed 6 years ago by ncohen

  • Cc ncohen added

comment:6 Changed 6 years ago by mderickx

  • Cc mderickx added

comment:7 Changed 6 years ago by jhpalmieri

  • Cc jhpalmieri added

comment:8 Changed 6 years ago by 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

comment:9 follow-up: Changed 6 years ago by 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.

comment:10 in reply to: ↑ 9 Changed 6 years ago by 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.

comment:11 Changed 6 years ago by vbraun

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

Last edited 6 years ago by vbraun (previous) (diff)

comment:12 Changed 6 years ago by tkluck

  • Dependencies #13015 deleted
  • Keywords sd51 added

Remove circular dependency.

comment:13 Changed 5 years ago by vbraun

  • Branch set to u/vbraun/dev_guide

comment:14 Changed 5 years ago by vbraun

  • Authors set to Volker Braun
  • Commit set to 67a76032fda3ee140c3bc52422020ef722cbee52
  • Status changed from new to needs_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 5 years ago by 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

comment:16 Changed 5 years ago by 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.

comment:17 Changed 5 years ago by git

  • Commit changed from 67a76032fda3ee140c3bc52422020ef722cbee52 to 8663e66b0c5164322a0b552e5997e9d993f19d60

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

8663e66switched tabs to spaces
1489e69fixed long doctest

comment:18 Changed 5 years ago by 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

comment:19 Changed 5 years ago by git

  • Commit changed from 8663e66b0c5164322a0b552e5997e9d993f19d60 to ee0a882b1d3e3c3f70a992b2a6b19035b3cc422b

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 5 years ago by 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.

comment:21 follow-up: Changed 5 years ago by 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

comment:22 Changed 5 years ago by mmezzarobba

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 5 years ago by vbraun

  • 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 5 years ago by 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.

comment:25 Changed 5 years ago by vbraun

  • Branch changed from u/vbraun/dev_guide to u/mmezzarobba/dev_guide
  • Commit changed from ee0a882b1d3e3c3f70a992b2a6b19035b3cc422b to 3aa6943c2bb248ea85039bb2371bf0902f90fca1

New commits:

3aa6943developer guide: minor rewordings

comment:26 Changed 5 years ago by git

  • Commit changed from 3aa6943c2bb248ea85039bb2371bf0902f90fca1 to 13c06b71fead7772a7fe754e8af98ea0eae5d7a1

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

13c06b7git dev guide review: update broken links

comment:27 Changed 5 years ago by git

  • Commit changed from 13c06b71fead7772a7fe754e8af98ea0eae5d7a1 to 7eb90497a4f0d75ca1ec1913badada127e288e16

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 5 years ago by git

  • Commit changed from 7eb90497a4f0d75ca1ec1913badada127e288e16 to f0c78611e175a5aa757bd86ca48f44ae5d232aa5

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

f0c7861git dev guide: add svg version of flowchart.dia

comment:29 Changed 5 years ago by git

  • Commit changed from f0c78611e175a5aa757bd86ca48f44ae5d232aa5 to cfe4d2efd816ccf3dad2c0d6ad4e5229e98959d1

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

cfe4d2egit dev guide review: workflows.rst

comment:30 Changed 5 years ago by 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.

comment:31 Changed 5 years ago by git

  • Commit changed from cfe4d2efd816ccf3dad2c0d6ad4e5229e98959d1 to a8e2dbe5122a3533225538a80d1102636c86fd2f

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

a8e2dbedev guide: use consistent capitalization in titles

comment:32 follow-up: Changed 5 years ago by vbraun

  • Branch changed from u/mmezzarobba/dev_guide to u/vbraun/dev_guide
  • Commit changed from a8e2dbe5122a3533225538a80d1102636c86fd2f to ee0a882b1d3e3c3f70a992b2a6b19035b3cc422b

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 5 years ago by mmezzarobba

  • Branch changed from u/vbraun/dev_guide to u/mmezzarobba/dev_guide
  • Commit changed from ee0a882b1d3e3c3f70a992b2a6b19035b3cc422b to 82e3d2e22e5f7eb880d7ee71a1984b11723de002
  • Reviewers set to 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 5 years ago by vbraun

  • Branch changed from u/mmezzarobba/dev_guide to u/vbraun/dev_guide

comment:35 Changed 5 years ago by vbraun

  • Commit changed from 82e3d2e22e5f7eb880d7ee71a1984b11723de002 to 6582fca9b2e4075cdea11b75bda6d6fc432d329a

I ported Robert's commits over...


New commits:

6582fcaUnneeded Cython setup
a27225aMinor coding_basics tweaks
7547aeeStreamline introduction

comment:36 Changed 5 years ago by vbraun

  • Status changed from needs_review to closed

comment:37 Changed 5 years ago by ncohen

O_o

Closed ?

Nathann

comment:38 Changed 5 years ago by vbraun

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

comment:39 Changed 5 years ago by ncohen

nonoono it's about the review ? O_o

Nathann

comment:40 Changed 5 years ago by vbraun

You had your chance

comment:41 Changed 5 years ago by 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

comment:42 Changed 5 years ago by vbraun

I reviewed Marc & Roberts changes.

comment:43 Changed 5 years ago by vbraun

  • Resolution set to fixed

Script forgot to set "Resolution: fixed"

comment:44 Changed 5 years ago by 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.

Note: See TracTickets for help on using tickets.