Opened 12 years ago

Closed 11 years ago

#2422 closed task (fixed)

Update Programming Guide

Reported by: jason Owned by: tba
Priority: major Milestone: sage-3.1.2
Component: documentation Keywords:
Cc: Merged in:
Authors: Reviewers:
Report Upstream: Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description

The programming guide should be updated:

  1. Instructions about working with trac (posting a patch, the "[with patch, needs review]", the review process, etc.)
  1. Expectations for patches (doctests and documentation, clean code, can be slow as an initial version, but if it's a naive way to do things when it could be faster, it should probably be mentioned, references for algorithms if it is an algorithm from a paper, etc.)
  1. Instructions on creating patches instead of bundles, maybe a short introduction to queues.
  1. Say that you really should go ask people to review your patch and then follow up and make sure the patch doesn't fall through the cracks.
  1. Instructions for running the doctests to check for failures.
  1. Expectations and instructions for creating spkgs

Change History (5)

comment:1 Changed 12 years ago by jason

Also, we probably ought to reorganize the guide so that it's very, very easy for a person to pick it up and start doing at least small fixes. Maybe put the short mercurial tutorial in the very front with a small documentation-fixing example or an example of adding a simple function.

comment:2 Changed 12 years ago by mabshoff

This ticket is a collection of various things to do. It would be better if each of the listed tasks would be its own ticket (some already are) since it seems unlikely that all of the above issues will be solved in on patch and during one merge cycle. We should wait past Doc Day 2 how much happens there, but it is likely that once a patch has been merged this ticket will be closed and the left overs will be moved to new ticket.

Cheers,

Michael

comment:3 in reply to: ↑ description Changed 12 years ago by mabshoff

Replying to jason:

The programming guide should be updated:

  1. Instructions about working with trac (posting a patch, the "[with patch, needs review]", the review process, etc.)

This is #1648.

  1. Expectations for patches (doctests and documentation, clean code, can be slow as an initial version, but if it's a naive way to do things when it could be faster, it should probably be mentioned, references for algorithms if it is an algorithm from a paper, etc.)

Also partly covered by #1648.

  1. Instructions on creating patches instead of bundles, maybe a short introduction to queues.

The way to create patches is already in the manual. What is needed is to tell people to use bundles only in special situations and to change the default example in that section away from bundles.

  1. Say that you really should go ask people to review your patch and then follow up and make sure the patch doesn't fall through the cracks.

This is also covered by #1648.

  1. Instructions for running the doctests to check for failures.

I am not sure, but it seems obvious to do. I also mention it in the material I have written for #1648.

  1. Expectations and instructions for creating spkgs

#1647 - so there isn't much meat left for this ticket :)

I will be working on #1647 and #1648 once 2.10.3 is out and most likely during Doc Day 2.

Cheers,

Michael

comment:4 Changed 11 years ago by mabshoff

This ticket can be closed once #3905 has been merged.

Cheers,

Michael

comment:5 Changed 11 years ago by mabshoff

  • Resolution set to fixed
  • Status changed from new to closed

Since #3905 has been merged this can be closed. In case you want improvements please open a specific followup ticket.

Cheers,

Michael

Note: See TracTickets for help on using tickets.