Opened 4 years ago

Closed 4 years ago

#17545 closed enhancement (fixed)

Rephrase the 'Reporting bugs' section of the developer's manual

Reported by: ncohen Owned by:
Priority: major Milestone: sage-6.5
Component: documentation Keywords:
Cc: kcrisman, vdelecroix, tmonteil Merged in:
Authors: Nathann Cohen Reviewers: Karl-Dieter Crisman
Report Upstream: N/A Work issues:
Branch: f6c51cf (Commits) Commit: f6c51cfe94eb0f01eba6600082bea267f6049dd9
Dependencies: #17534 Stopgaps:

Description

The current "Reporting Bugs" section of the developer's manual is rather verbose, and contain information that is already explained elsewhere:

  • How to create a ticket
  • The meaning of a ticket's fields

http://www.sagemath.org/doc/developer/trac.html#reporting-bugs

With this branch, the description points toward those sections instead of repeating it (partially) here. Also, some information that was there and not in the other section was moved there.

I also added a (short) explanation of what the color of the branch's name means. But there was no "How to merge with the latest beta" section anywhere, so it's still somehow a dead end. Better than nothing though.

Change History (8)

comment:1 Changed 4 years ago by ncohen

  • Branch set to public/17545
  • Component changed from PLEASE CHANGE to documentation
  • Status changed from new to needs_review
  • Type changed from PLEASE CHANGE to enhancement

comment:2 Changed 4 years ago by git

  • Commit set to 601a80180604d64b1498a5e0ea2a76cec78da9ad

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

4ae1934trac #17534: The reviewer's checklist
a4615b0trac #17534: Reviewers' comments
375d087trac #17534: Reviewer's comments
4ff64c1trac #17534: Reviewer's comments
79bbb56Final English and other fixes
601a801trac #17545: Rephrase the 'Reporting bugs' section of the developer's manual

comment:3 Changed 4 years ago by kcrisman

  • Reviewers set to Karl-Dieter Crisman

I don't have any problems with the content of this. I hope to check the actual look/links etc. momentarily.

comment:4 follow-up: Changed 4 years ago by kcrisman

Just curious as to why you have two headers for this.

+.. _trac-bug-report:
+
+.. _section-trac-bug-report:

Would one suffice, or is there a technical reason this is necessary?

Because you have a sub point before "You might be asked..." (I think) but not before "If you do not ..." there is an extra space before the latter. I don't know if it matters, but it looks inconsistent.

I also notice (not introduced by you) that

All changes to Sage source code have to go through the Sage trac development server. 

but Trac is not capitalized. If you want to, you could fix that here instead of someone opening a trivial ticket...

(Edit: otherwise this is fine!)

Last edited 4 years ago by kcrisman (previous) (diff)

comment:5 Changed 4 years ago by git

  • Commit changed from 601a80180604d64b1498a5e0ea2a76cec78da9ad to f6c51cfe94eb0f01eba6600082bea267f6049dd9

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

f6c51cftrac #17545: review

comment:6 in reply to: ↑ 4 Changed 4 years ago by ncohen

Hello !

Just curious as to why you have two headers for this.

I fought hard against this while writing the branch and thought that it was the only way out. Turns out that now it works without that. Sooooo let's say "fixed" :-P

Because you have a sub point before "You might be asked..." (I think) but not before "If you do not ..." there is an extra space before the latter. I don't know if it matters, but it looks inconsistent.

Here again I tried a lot, I tried this [1] and inserted empty math environments, and other tricks... I don't know hwo to fix that, it actually looks like a docutils bug. I agree that it is not pretty but I do not know how to make it better.

but Trac is not capitalized. If you want to, you could fix that here instead of someone opening a trivial ticket...

Done.

Nathann

[1] http://docutils.sourceforge.net/FAQ.html#how-to-indicate-a-line-break-or-a-significant-newline

comment:7 Changed 4 years ago by kcrisman

  • Status changed from needs_review to positive_review

comment:8 Changed 4 years ago by vbraun

  • Branch changed from public/17545 to f6c51cfe94eb0f01eba6600082bea267f6049dd9
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.