| 8 | | * Show who uploaded package and when |
| 9 | | * Darcs (and other VC) integration (see below). |
| 10 | | * The page for a package could include information from standard README, INSTALL, NEWS etc files. Those files could contain wikitext-like markup. (Or haddock markup, since we already have to parse descriptions? Or HTML fragments?) |
| 11 | | cf [http://www.cs.chalmers.se/~bringert/darcs/hask-home/doc/ hask-home]. |
| 12 | | * The package page could maybe have links to packages which depend on it? |
| | 8 | Currently: |
| | 9 | * Haddock documentation for a library package is placed in the directory |
| | 10 | ''archive''`/`''pkg''`/`''version''`/doc/html`. |
| | 11 | If this directory exists, the package script renders exposed module names as links |
| | 12 | to the documentation for the corresponding modules. |
| | 13 | * The haddock documentation links to types, modules etc. in the packages it depends on. |
| | 14 | * Links across packages always point to the latest version of the target package. |
| | 15 | This way we don't have to worry about re-haddocking dependent packages whenever |
| | 16 | a package at the bottom of the tree is updated. |
| | 17 | Some dependencies may go wrong, if a package depends on a specific version of |
| | 18 | another package for example, but this way is simple at least. |
| | 19 | * The `--html-location` option of the development version of Cabal is used to make |
| | 20 | haddock generate links pointing at ''archive''`/`''pkg''`/latest/doc/html`, |
| | 21 | which will be a symbolic link to an `html` directory. |
| | 22 | * Some trial runs have been made, generating documentation for some packages. |
| | 23 | The missing part is automatic generation of the documentation. |
| | 24 | Some possibilities: |
| | 25 | * Avoid running arbitrary code to generate the Haddock by restricting ourselves |
| | 26 | to packages that just use the simple build system and only Haddock those, then we don't |
| | 27 | need to worry about arbitrary code. But some important packages use autoconf, and |
| | 28 | we won't be able to do those. We could use the new `Build-Type` field to tell us |
| | 29 | whether a package uses the simple build system or not. |
| | 30 | * We could use Cabal to build the Haddock docs, but then prerequisite packages must be |
| | 31 | configured, built, haddocked and installed (in a local package database), so we would |
| | 32 | not be able to avoid running arbitrary code. |
| | 33 | To be safe, this could be done in a chroot jail. |
| | 34 | The latter choice seems cleanest. |
| | 35 | |
| | 36 | Should building happen during upload, between upload and arriving in the archive, or later? |
| | 37 | Probably the latter. |
| | 38 | |
| | 39 | Other things we could do: |
| | 40 | * Link to the build log from the package page. |
| | 41 | * Generate a [http://www.haskell.org/hoogle Hoogle] database for searching. |
| | 42 | * Syntax highlighted source code with links from haddock directly to function definitions? |
| | 43 | * Test with different compiler & versions, report which ones work |
| | 44 | * Run test suites |
| | 45 | |
| | 46 | == Package properties == |
| | 47 | |
| | 48 | The .cabal file contains a number of internal properties of the package. |
| | 49 | There will be a need to add other attributes of uploaded packages, without modifying |
| | 50 | the .cabal file. |
| | 51 | This could be achieved with a plain text tags file, outside of the Cabal package, |
| | 52 | providing a mapping from attributes to values (both strings). |
| | 53 | Example attributes: |
| | 54 | * who uploaded the package |
| | 55 | * when it was uploaded |
| | 56 | * which versions of compilers it has been built or tested with |
| | 57 | * packages that depend on this one (?) |
| | 58 | * user-supplied descriptions of the package |
| | 59 | * feedback from users' [wiki:CabalInstall cabal-install] runs (?) |
| | 60 | These attributes could be shown by the package display and used for searching. |
| | 61 | |
| | 62 | They could also be used for a more sophisticated form of classification, |
| | 63 | as in [http://debtags.alioth.debian.org/ debtags], |
| | 64 | but multiple categories should be enough for now. |
| | 65 | (Also, this use arguably belongs in the .cabal file.) |
| 15 | | * words in synopsis or description |
| 16 | | * package name |
| 17 | | * module name |
| 18 | | * exported names |
| 19 | | * author / maintainer / uploader |
| 20 | | * ranges of upload date |
| 21 | | * by Hoogle? :) |
| 22 | | * by tags (below) ? |
| 23 | | |
| 24 | | == Uploads == |
| 25 | | |
| 26 | | * auto building (see below) |
| 27 | | * Haddock (see below) |
| 28 | | * Generate change information between package versions: functions added/removed/changed, modules added/removed. |
| 29 | | * When a new version of a package is uploaded, generate a list of packages that will be affected and possibly |
| 30 | | broken by the upload, and notify the uploader, and test the builds. |
| 31 | | * RSS feed could distinguish new packages from upgrades |
| 32 | | |
| 33 | | == Auto-building == |
| 34 | | |
| 35 | | * Test with different compiler & versions, report which ones work |
| 36 | | * Build packages |
| 37 | | * Build Haddock docs (see below) |
| 38 | | * Run test suites |
| 39 | | * Record feedback from users' [wiki:CabalInstall cabal-install] runs? |
| 40 | | |
| 41 | | Should building happen during upload, between upload and arriving in the archive, or later? |
| | 68 | We already have [http://www.haskell.org/hoogle Hoogle] for searching for names in modules. |
| | 69 | As the package collection grows, we'll also need a package-level search facility. |
| | 70 | We might like to search by |
| | 71 | * fields of the .cabal file, e.g. package name, words in synopsis or description, |
| | 72 | module name, author / maintainer. |
| | 73 | * attributes in the tags file, e.g. uploader, ranges of upload date, compilers it |
| | 74 | builds with, user-supplied descriptions. |
| | 75 | * combinations of these |
| 55 | | * The generated haddock should link to types, modules etc. in the packages which it depends on. |
| 56 | | * If the directory ''archive''`/`''package''`/`''version''`/doc/html` exists, the package script renders exposed module names as links to the documentation for the corresponding modules. |
| 57 | | * The Haddock for the latest version of each package is to be placed at a known location, ''archive''`/`''package''`/latest/doc/html`, a symbolic link to one of those directories. |
| 58 | | * Links across packages always point to the latest version of the target package. |
| 59 | | This way we don't have to worry about re-haddocking dependent packages whenever |
| 60 | | a package at the bottom of the tree is updated. Some dependencies may go wrong, |
| 61 | | if a package depends on a specific version of another package for example, but |
| 62 | | this way is simple at least. |
| 63 | | * Avoiding running arbitrary code to generate the Haddock: if we restricted ourselves |
| 64 | | to packages that just use the simple build system and only Haddock those, then we don't |
| 65 | | need to worry about arbitrary code. But some important packages use autoconf, and |
| 66 | | we won't be able to do those. Also, we can't tell whether a package uses the simple |
| 67 | | build system or not: we need the field in the .cabal file to tell us (the new `Build-Type` field). |
| 68 | | * We could use Cabal to build the Haddock docs, but then: |
| 69 | | * Prerequisite packages must be configured, built, haddocked and installed (in a local package database), so we would not be able to avoid running arbitrary code (and we might as well build and install this package too). |
| 70 | | To be safe, this could be done in a chroot jail. |
| 71 | | * The resulting haddock output will contain local filenames, which will have to be mangled to point to the standard location. |
| 72 | | Alternatively we could tweak the `haddock-html` field of each `.installed-package-info` prior to installation. |
| 73 | | * Syntax highlighted source code with links from haddock directly to function definitions? |
| | 89 | * The page for a package could include information from standard README, INSTALL, NEWS etc files. Those files could contain wikitext-like markup. (Or haddock markup, since we already have to parse descriptions? Or HTML fragments?) |
| | 90 | cf [http://www.cs.chalmers.se/~bringert/darcs/hask-home/doc/ hask-home]. |
| 77 | | Several people felt that a collection of categories, even overlapping, was too inflexible, and that we should use a system of facets and tags, as in [http://debtags.alioth.debian.org/ debtags]. |
| 78 | | A ''facet'' is a dimension of classification; a ''tag'' is a value for a facet. |
| 79 | | A package would be described by a set of ''facet''{{{::}}}''tag'' pairs. |
| 80 | | |
| 81 | | * these could be used in a more sophisticated search interface. |
| 82 | | * we'd probably want a registry of facets and tags. |
| 83 | | * some facets describe packages, e.g. {{{field}}}, {{{interface}}}, {{{use}}}, while others describe particular versions, e.g. {{{builds-with}}}, {{{tested-with}}}. |
| 84 | | * we'd want to be able to attach at least some facet-tag pairs some time after uploading (e.g. {{{builds-with::ghc-19.2}}}). |
| 85 | | Since packages may not be updated frequently, we'd probably want to add others too. |
| 86 | | |
| 87 | | Multiple categories should be enough for now, though. |
| | 94 | * auto building (see above) |
| | 95 | * Haddock (see above) |
| | 96 | * Generate change information between package versions: functions added/removed/changed, modules added/removed. |
| | 97 | * When a new version of a package is uploaded, generate a list of packages that will be affected and possibly |
| | 98 | broken by the upload, and notify the uploader, and test the builds. |
| | 99 | * RSS feed could distinguish new packages from upgrades |
