Opened 11 years ago

Closed 6 years ago

#9690 closed enhancement (fixed)

explain differences between standard, optional, and experimental packages

Reported by: mvngu Owned by: drkirkby
Priority: major Milestone: sage-duplicate/invalid/wontfix
Component: documentation Keywords:
Cc: schilly Merged in:
Authors: Reviewers: Jeroen Demeyer
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description

The Developer's Guide should distinguish between the following Sage packages: standard, optional, and experimental. See this sage-devel thread for a start.

Change History (14)

comment:1 Changed 11 years ago by schilly

  • Cc schilly added

comment:2 Changed 11 years ago by schilly

Since I wrote the definition in the thread, here a revised summary:

  • standard
    • included in sage by default
    • runs on all supported platforms and systems
    • well tested, this means all needed functionality is doctested via the sage library
    • sage project as a whole is responsible
    • updates go through trac + extensive review
  • optional
    • not included by default
    • should run on all platforms, unless explicitly noted (i.e. this could be a reason why it cannot be a standard package, e.g. "valgrind")
    • sage project as a whole is responsible
    • updates go through trac + review
  • contributed (formerly known as "experimental")
    • not included by default
    • sage project is not responsible, it's the responsibility of the contributor(s) (maintainer(s)) that it works. he or she is also the dedicated contact person.
    • doesn't need to run on all platforms, maybe it doesn't run at all (i.e. broken optional package)
    • updates to through trac, with comments, date and maybe a discussion, but there is no review.

All three types follow the common layout of an SPKG, i.e. the install and (optional) check scripts, the mercurial repository excluding the untouched "src" dir and the SPKG.txt from where it should be possible to extract the description text. (sage -pkg checks that anyways, doesn't it?)

comment:3 Changed 11 years ago by drkirkby

A few comments

Supported platforms

This bit of the developers guide should have a link to http://wiki.sagemath.org/SupportedPlatforms where the supported platforms are listed. (There needs to be other links in other parts of the developers and user's guide too, but this is one place where a link needs to be). Otherwise people wont know what platforms their optional packages are supposed to be tested on.

Optional packages

There should be a comment that optional packages must work on all supported platforms unless there is a very good reason why it can't be run on all platforms. (Valgrid is the obvious example of where there's a very good reason). What I am keen to avoid is an optional package, saying "It's only supported on Linux", and not making sufficient effort to actually get it working on any other platforms.

I think if optional packages are .spkg files, then there should be an spkg-check file to run any self-tests that package may have.

Experimental packages

Although it should not be a requirement, I think we should say people are encouraged to add doc tests and if appropriate an SPKG.txt and spkg-check file.

Is anyone intending to write this? I would like to see this in the developers guide, but don't know how to write the documentation myself, and have so many tickets I'm involved in now, this is not something I have a lot of time for myself. Someone who knows what they are doing can probably do it in a tenth of the time I could.

Dave

comment:4 Changed 11 years ago by drkirkby

I personally think the word "Experimental" does imply the packages are less well tested than "Optional" whereas the same can not be said of "Contributed". But I guess this is a matter of taste - it's not something I have a big issue with.

Dave

comment:5 Changed 11 years ago by drkirkby

Also, if renamed, then the top level Makefile, and possible other files would need editing. Is it really worth renaming them?

Dave

comment:6 Changed 11 years ago by drkirkby

Since nobody appears to be doing this, I'll write this page, though it would be good to get some agreement on a few issues before I write it.

Dave

comment:7 Changed 11 years ago by drkirkby

  • Owner changed from mvngu to drkirkby

comment:8 Changed 8 years ago by jdemeyer

  • Milestone changed from sage-5.11 to sage-5.12

comment:9 Changed 8 years ago by vbraun_spam

  • Milestone changed from sage-6.1 to sage-6.2

comment:10 Changed 7 years ago by vbraun_spam

  • Milestone changed from sage-6.2 to sage-6.3

comment:11 Changed 7 years ago by vbraun_spam

  • Milestone changed from sage-6.3 to sage-6.4

comment:12 Changed 6 years ago by jdemeyer

  • Milestone changed from sage-6.4 to sage-duplicate/invalid/wontfix
  • Reviewers set to Jeroen Demeyer
  • Status changed from new to needs_review

Please see #19267 which has a section about this.

comment:13 Changed 6 years ago by jdemeyer

  • Status changed from needs_review to positive_review

comment:14 Changed 6 years ago by vbraun

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