├── CONTRIBUTING.md ├── README.md ├── cookbook.md ├── policy.md └── revisions-information.md /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Please include the following information when filing Hackage package issues 2 | 3 | 1. How and when was the maintainer for the package requiring action contacted? 4 | 2. If available, a link to the filed issue in the upstream issue tracker 5 | 3. If not evident from 2., how to reproduce the issue (and if known, how to fix it) 6 | 4. How critical is this, what's the impact of this breakage? E.g. how many dependent packages are affected by this? Which GHC versions are affected? 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Hackage Trustee Issue Tracking 2 | 3 | This is an issue tracker for coordinating Hackage maintainance and trustee operations **for packages hosted** on [Hackage](https://hackage.haskell.org) that may require intervention by [Hackage trustees](https://hackage.haskell.org/packages/trustees/). 4 | 5 | Please make sure you've made an effort to contact the upstream maintainer for a package needing attention before filing issues here. See also the [issue filing guidelines](CONTRIBUTING.md) for what to include in the issue report. 6 | 7 | The process for trustee operations is described in detail in [the policy document](https://github.com/haskell-infra/hackage-trustees/blob/master/policy.md). 8 | 9 | For bugs and issues in the **software component `hackage-server`** please go to https://github.com/haskell/hackage-server instead. 10 | 11 | The trustees can also be contacted at [hackage-trustees@haskell.org](mailto:hackage-trustees@.haskell.org) 12 | -------------------------------------------------------------------------------- /cookbook.md: -------------------------------------------------------------------------------- 1 | # Cookbook for common build-failures 2 | 3 | This document gives recipes for addressing common compile errors and 4 | other meta-data issues, as well as best practices for performing 5 | meta-data revisions. 6 | 7 | ## Compile errors/symptoms and their solutions 8 | 9 | **Problem:** 10 | 11 | Implicit import declaration: 12 | Ambiguous module name `Prelude': 13 | it was found in multiple packages: base haskell98-2.0.0.0 14 | 15 | **Fix:** Add constraint `haskell98 < 2` 16 | 17 | **Explanation:** Starting with version 2.0.0.0, `haskell98` started including the `Prelude` module. 18 | 19 | ---- 20 | 21 | **Problem:** 22 | 23 | ``` 24 | Could not find module `MyModule' 25 | Use -v to see a list of the files searched for. 26 | ``` 27 | 28 | **Fix:** Add two lines right under `library` keyword 29 | 30 | ``` 31 | -- some comment explaining why this package ver is marked bad 32 | build-depends: base<0 33 | ``` 34 | 35 | **Explanation:** package is non-buildable and non-fixable by any metadata 36 | change: missing file etc. By adding non-solvable constraint, we tell Cabal to 37 | never pick this version. 38 | 39 | ---- 40 | 41 | **Problem:** 42 | 43 | ``` 44 | Ambiguous occurrence ‘defaultTimeLocale’ 45 | It could refer to either ‘System.Locale.defaultTimeLocale’, imported from ‘System.Locale’ 46 | or ‘Data.Time.defaultTimeLocale’, imported from ‘Data.Time(.Format.Locale)’ 47 | ``` 48 | 49 | **Metadata fix:** Add a `time < 1.5` constraint. 50 | 51 | **Source fix:** Import `defaultTimeLocale` from `time-locale-compat:Data.Time.Locale.Compat` 52 | 53 | **Explanation:** `time-1.5` added `defaultTimeLocale` obsoleting `old-locale`. 54 | 55 | --- 56 | 57 | **Problem** 58 | 59 | ``` 60 | Could not deduce (Eq a) arising from a use of ‘==’ from the context: Num a 61 | ``` 62 | 63 | ``` 64 | Could not deduce (Show a) arising from a use of ‘show’ from the context: Num a 65 | ``` 66 | 67 | **Metadata fix:** Add a `base < 4.5` constraint. 68 | 69 | **Explanation:** `Num` lost its Haskell2010-compliant `Eq`/`Show` superclasses in `base-4.5` 70 | 71 | --- 72 | 73 | **Problem** 74 | 75 | ``` 76 | Ambiguous occurrence `catch' 77 | It could refer to either `Prelude.catch', 78 | imported from `Prelude' at Network/HTTP/Client/TLS.hs:4:8-30 79 | (and originally defined in `System.IO.Error') 80 | or `Control.Exception.catch', 81 | ``` 82 | 83 | **Metadata fix:** Add a `base >=4.6` constraint. 84 | 85 | **Explanation:** `catch` was removed from `Prelude` in `base-4.6` 86 | 87 | --- 88 | 89 | **Problem** 90 | 91 | ``` 92 | Could not find module ‘Control.Monad.Trans.Either’ 93 | Perhaps you meant 94 | Control.Monad.Trans.Writer (from transformers-0.5.5.0) 95 | Control.Monad.Trans.Writer (needs flag -package transformers-0.3.0.0) 96 | Control.Monad.Trans.Writer (needs flag -package transformers-0.4.3.0) 97 | ``` 98 | 99 | **Metadata fix:** Add a `either < 5` constraint. 100 | 101 | **Explanation:** `Control.Monad.Trans.Either` was removed from `either` in `either-5` 102 | 103 | --- 104 | 105 | **Problem** 106 | 107 | The `.cabal` file contains disabled components (i.e. via `buildable:False`) and the build fails with 108 | 109 | ``` 110 | Configuring foo-1.2.3... 111 | setup: At least the following dependencies are missing: 112 | process -any, temporary >=1.1 113 | ``` 114 | 115 | **Metadata fix:** If missing, add a `custom-setup` stanza and set a lower bound `setup-depends: Cabal >= 1.24`. 116 | 117 | **Explanation:** See [Cabal #3881](https://github.com/haskell/cabal/issues/3881) 118 | 119 | --- 120 | 121 | **Problem:** 122 | 123 | Several different errors: Missing modules or identifiers, name clashes. 124 | This is a quick reference for adding bounds for common errors. 125 | 126 | **Fix:** If the identifier is missing/clashes add the constraint on the RHS. 127 | 128 | ``` 129 | base upper bounds: 130 | Illegal bang-pattern (use -XBangP..) => base < 4.4 131 | Prelude.catch => base < 4.6 132 | 133 | base lower bounds: 134 | Data.Monoid.<> => base >= 4.5 135 | Data.Bits.zeroBits => base >= 4.7 136 | Prelude.& => base >= 4.8 137 | Control.Concurrent.forkFinally => base >= 4.6 138 | atomicModifyIORef' => base >= 4.6 139 | CUInt => base >= 4.5 140 | 141 | bytestring: 142 | Data.ByteString.Builder => bytestring >= 0.10.2 143 | Data.ByteString.Lazy.Builder => bytestring >= 0.10 144 | Data.ByteString.Lazy.toStrict => bytestring >= 0.10 145 | 146 | containers: 147 | Data.IntMap.Strict => containers >= 0.5 148 | Data.Map.Strict => containers >= 0.5 149 | 150 | getModificationTime :: _ -> IO UTCTime => directory >= 1.2 151 | 152 | Attoparsec.Done/Fail/Partial => attoparsec < 0.10 153 | Scientific vs Number => aeson < 0.7 154 | 155 | Control.Monad.Trans.Resource & conduit => conduit < 0.3 156 | 157 | MonadThrow.monadThrow doesn't exist => exceptions < 0.4, resourcet < 1.1 158 | 159 | Data.Serialize.Builder => cereal < 0.5 160 | 161 | crypto packages: 162 | Crypto.Cipher.AES & depends on cryptocipher => cryptocipher < 0.5 163 | Crypto.Cipher.RSA & depends on cryptocipher => cryptocipher < 0.5 164 | Crypto.Cipher.AES.Key/keyOfCtx => cipher-aes < 0.2 165 | Crypto.Modes.IV => crypto-api < 0.11 166 | Crypto.Random.AESCtr.genRandomBytes => cprng-aes < 0.5 167 | Couldn't match `Int' with `AESRNG' => cprng-aes < 0.3 168 | ``` 169 | 170 | ## Best practice for managing meta-data 171 | 172 | Below, multiple common schemes used to ensure accurate dependency 173 | meta-data are described, together their respective trade-offs and 174 | associated costs. 175 | 176 | The architecture of the Hackage/Cabal ecosystem make it necessary to 177 | optimise the way meta-data is managed in order to keep the overall 178 | system sustainable. Specifically, the meta-data management protocols 179 | needs to ensure that the amount of meta-data updates are minimised and 180 | that the configuration space is kept reasonably compact. 181 | 182 | A couple of general guiding principles are: 183 | 184 | - New package releases ought to be avoided when a meta-data revision would suffice 185 | - New releases or meta-data updates *for the sole purpose* of relaxing dependencies in test-suites and/or benchmark suites ought to be avoided. Such meta-data updates shall be saved up for the next release or the next "useful" revision. 186 | 187 | In the descriptions below, the term *active releases* is to denote 188 | releases which are deemed the most recent ones and are considered 189 | actively supported (this is usually only one: the most recent 190 | version). 191 | 192 | ### The *correct* way 193 | 194 | - Upload releases with proper [PVP](http://pvp.haskell.org)-style version bounds 195 | - Relax version bounds for *active releases* via revisions as needed 196 | 197 | *Static cost: 1 meta-data revision per compatible-dependency-upgrade-event* 198 | 199 | It has the benefit of reducing the overall risk of compile failures or 200 | compilable unsound configurations to a minimum. And by the more 201 | conservative approach to opt-in to extend the solution space rather 202 | than opt-out of incorrect parts of the solution space, don't put as 203 | much pressure on the maintainer to step in. 204 | 205 | Moreover, this keeps the configuration space small which is beneficial 206 | for the cabal solver as it allows it to operate more efficiently and 207 | discard less interesting parts of the space sooner. This typically 208 | results in a configuration space which gets larger towards newer 209 | versions. 210 | 211 | If a package has frequent releases (in relation to its dependencies), 212 | this scheme is very economical versions can often be relaxed as part 213 | of a new release. 214 | 215 | From the correctness point of view as well as the overall cost, this 216 | represents the optimal scheme. This results in packages that from 217 | experience cause the least problems on Hackage, and therefore the 218 | least amount of work from all parties involved. 219 | 220 | Moreover, this can be complemented with automated systems (such as 221 | Stackage or via `packdeps` + Travis CI) which can notify package 222 | authors when new package releases of dependencies become available 223 | which happen to be out of bounds. 224 | 225 | Because __this scheme is the overall optimal one__, this is also the 226 | only scheme that's actually in full compliance with the stated Hackage 227 | guidelines. 228 | 229 | ### The *lagging* way 230 | 231 | - Upload new releases without upper bounds (assuming they're compatible w/ most recent depending package versions on Hackage), and... 232 | - ... add upper bounds to previous releases that have become non-*active* by the new release 233 | - When unsound/bad install-plans are detected, add upper bounds ASAP 234 | 235 | *Static cost: 1 meta-data revision per release __plus__ 1 meta-data revision per incompatible-dependency-upgrade-event* 236 | 237 | In this scheme, only *active* releases can have upper bounds omitted. 238 | 239 | The problem with this scheme is that there is a constant risk that a 240 | new major release of a dependency allowed by the lack of an upper 241 | bound may result in an unsound configuration. However, since it's not 242 | possible to instantly revalidate each depending package when a new 243 | major release of a dependency occurs, this introduces a dangerous 244 | "lag" between Hackage's meta-data regressing into an unsound 245 | state and recovering again. 246 | 247 | This "lag" is made up of the time from when the breaking dependency 248 | gets uploaded to the time when the unsoundness is detected plus the 249 | time needed for a maintainer stepping in and recovering correctness by 250 | adding the necessary upper bound. 251 | 252 | This scheme results in the same meta-data during "sound" phases as the 253 | "correct" way described in the previous section; however, this scheme 254 | has scalability issues as the more Hackage grows, the more likelihood 255 | of at one or more packages becoming unsound increases as well. If this 256 | increases too much, a point would be reached at which there is always 257 | multiple unsound packages. 258 | 259 | Another problem with this scheme is that by the time the problem has 260 | been detected, install-plans using unsound configurations (which 261 | happen to compile) may have started to become used by users (and which 262 | may not even exhibit the incorrectness as they may not use the broken 263 | codepaths). If such install-plans are retroactively prohibited, this 264 | results in a bad user-experience, and results in violation of the 265 | invariant that a meta-data revision shall not result in existing 266 | install-plans becoming illegal. 267 | 268 | So this scheme is very sensitive to being able to detect & resolve 269 | meta-data regressions in a *very* timely matter, as otherwise the 270 | overall system collapses due to a build-up of not-yet-fixed unsound 271 | meta-data. 272 | 273 | ### The *sloppy* way 274 | 275 | - Upload new releases without (upper) bounds (-"-) 276 | - When unsound/bad install-plans are detected, 277 | - add (all) upper bounds to all affected releases 278 | 279 | *Static cost: 1 meta-data revision per release.* 280 | 281 | This is similiar to the *lagging* way, typically increases the 282 | risk-exposure to more releases than just the next-to-last one, and 283 | thereby also misses the goal to keep the configuration space 284 | reasonably (and therefore results in a different meta-data situation 285 | than the other workflows!) compact to aid constraint solving. 286 | 287 | Due to the increased configuration space, the combinatorics involved 288 | make it even more prohibitive than the *laggy* scheme (if not 289 | impossible) to cover validating new install-plans becoming possible 290 | due to the appearance of new major versions. 291 | 292 | The revision-cost is actually lower than for the *lagging* scheme; for 293 | packages with a small number of total releases combined with a high 294 | amount of direct frequently releasing dependencies, this scheme may 295 | also result in a smaller static cost. However, the aforesaid mentioned 296 | disadvantages make this scheme still less preferable to the *correct* 297 | and *lagging* schemes. 298 | 299 | ### The *worst* way 300 | 301 | - Upload new releases without (upper) bounds (-"-) 302 | - When unsound/bad install-plans are detected, 303 | - add the minimal amount of necessary upper bounds to all affected releases 304 | 305 | *Static cost: 1 meta-data revision per incompatible-dependency-upgrade-event __times__ number of affected releases* 306 | 307 | This has by far the worst overall cost-model of all schemes listed 308 | here and asymptotically leads 309 | to the very harmful situation where the number of meta-data revisions 310 | will eventually outnumber the amount of actual package releases by 311 | orders of magnitudes, while also amplifying the downsides already 312 | described for the *laggy* and *sloppy* schemes, and last but not least 313 | also being the most laborious workflow for both maintainers and 314 | trustees. 315 | 316 | In short, __this scheme is maximally detrimental to the Hackage/Cabal ecosystem__ 317 | and therefore ought to be avoided at any price as it isn't sustainable 318 | due to the prohibitive computational complexities involved. 319 | -------------------------------------------------------------------------------- /policy.md: -------------------------------------------------------------------------------- 1 | # Hackage trustee policy and procedures 2 | 3 | The Hackage trustees are a group of volunteers who are interested in 4 | the health of the package collection as a whole. This is different to 5 | the role of maintainers of individual packages. 6 | 7 | The trustees role is in many ways similar to that of the individuals 8 | who maintain the Haskell packages for the various Linux distributions. 9 | In Linux distributions the distribution maintainers seek to have their 10 | set of packages build and work together. The kinds of problems they 11 | deal with tend to be similar across many packages, and so they can 12 | become adept at spotting and solving them, where a maintainer of any 13 | individual package is likely to only encounter such problems once. In 14 | particular distribution maintainers are often involved in making minor 15 | fixes to packages and pushing those fixes back upstream. 16 | 17 | The Hackage trustees role is much like that of distribution maintainers 18 | but closer to upstream, and more centralised rather than duplicated 19 | across numerous Linux distributions. 20 | 21 | 22 | ## Mission statement 23 | 24 | The goal of the trustees is to make it easy for anyone to use packages 25 | that are hosted on Hackage, and maintain the overall health of Hackage 26 | infrastructure. Ideally users will always be able to find a suitable 27 | combination of packages and versions that work well together. 28 | 29 | Trustees strive to involve maintainers in this process as much as 30 | possible while being friendly, helpful, and respectful. In general, 31 | trustees aim to empower and educate maintainers about the tools at 32 | their disposal to better manage their own packages. We realize that 33 | not everyone shares our priorities and we do not want to take up 34 | anyone's time unnecessarily. For these cases we would like to find an 35 | arrangement that suits the maintainers wishes, while also not unduly 36 | burdening resources of trustees. Being a part of the hackage curation 37 | process is entirely optional. 38 | 39 | Trustee policies are intended to maximise the useful improvements 40 | trustees can make (or encourage others to make) to the collection 41 | while making sure the relationship with authors/maintainers is 42 | healthy. We do not want to discourage maintainers from using Hackage. 43 | We want processes (and if necessary automation) for each case that 44 | balances the ability of trustees to make useful improvements, with the 45 | legitimate concerns of authors/maintainers to maintain control and 46 | quality. 47 | 48 | Common trustee operations involve specifying or correcting metadata 49 | using revisions, but there are also uncommon operations involving 50 | uploads of new versions. The rest of this document contains details on 51 | which changes can be made in which circumstances, and with what 52 | necessary prior and subsequent communication. 53 | 54 | 55 | ## 1. Metadata-only changes: tightening constraints 56 | 57 | The trustees' view is that tightening constraints is very useful, 58 | and is pretty safe and obvious. It is safe in the sense that it 59 | does not make possible any configurations that were not previously 60 | possible. It's pretty obvious when it needs to be done because there 61 | is concrete evidence that certain combinations of versions do not in 62 | fact compile. 63 | 64 | (The only plausible danger is in accidentally over-constraining and 65 | excluding build configurations that did actually work. This is easily 66 | correctable.) 67 | 68 | Making these changes is also likely to be the bulk of the trustees' 69 | work and so the trustees want a process with low overheads. 70 | 71 | ### Policy/Procedure 72 | 73 | * trustees can edit .cabal file to constrain dependencies 74 | * maintainers should be notified via e-mail, by filing a bug tracker issue, or 75 | by sending pull request (in the future this step may be automated by hackage) 76 | 77 | ## 2. Metadata-only changes: relaxing constraints 78 | 79 | The trustees' view is that relaxing constraints should be done 80 | carefully, and ideally done by or checked by the package maintainers. 81 | Nevertheless there are cases where it is helpful. 82 | 83 | ### Policy/Procedure 84 | 85 | * trustees can edit .cabal file to relax dependencies 86 | 87 | * maintainers should be notified via e-mail, by filing a bug tracker 88 | issue, or by sending a pull request (in the future this step may be 89 | automated by hackage) 90 | 91 | * the default is to be opted in to allowing trustees to make these edits 92 | 93 | * (in the future) maintainers should be able to explicitly indicate 94 | whether trustees are able to relax constraints for their package 95 | 96 | * (in the future) if not, trustee's proposed edits are sent to the 97 | maintainers but not applied 98 | 99 | Trustees are expected to use this power judiciously and make sure they 100 | understand the packages involved and their APIs. In the first instance 101 | they should get maintainers to make changes. If maintainers are not 102 | available then they should use their judgement and consult with each 103 | other when in doubt. 104 | 105 | 106 | ## 3. Source changes: "simple" patches 107 | 108 | There are cases where maintainers are unavailable indefinitely or for 109 | long periods. This is not usually an urgent problem, but sometimes when 110 | a package has lots of others that depend on it, those other packages 111 | can be blocked from working with newer dependencies. For example a 112 | package that is not updated for a long period may block all packages 113 | that depend on it from working with a newer compiler or base library 114 | release. 115 | 116 | In such cases trustees should in the first instance work with the 117 | maintainers to make them aware and help them to make appropriate 118 | updates. 119 | 120 | Of course when maintainers are not available indefinitely, there is a 121 | procedure to allow a new volunteer to take over the package. Stopping 122 | short of that, when only very minor updates are needed it may be 123 | desirable to allow the trustees to make the update without securing a 124 | new volunteer maintainer. Similarly, if the maintainer(s) are not 125 | available for a prolonged period but do eventually return, it may be 126 | desirable in the meantime for the trustees to make simple updates when 127 | it affects important packages (directly or indirectly). 128 | 129 | Making source changes without the involvement of the maintainer (a 130 | so-called NMU -- non-maintainer upload) is certainly not ideal and so 131 | a careful procedure is called for. It should balance the benefits to 132 | the health of the package collection with the control of package 133 | author. 134 | 135 | ### Policy/Procedure 136 | 137 | 1. (Anyone) Send a pull request or open an issue to the offending 138 | packages source repository. If no source repository is 139 | available, send an e-mail. 140 | 2. (Anyone) After a while if there is no response, [open a ticket in 141 | the trustees issue tracker](https://github.com/haskell-infra/hackage-trustees/issues/new), 142 | linking to the pull request / issue, 143 | or describing/embedding the e-mail. Alternatively if problems 144 | are anticipated from the outset then file the issue immediately. 145 | 3. (Trustee) When the issue is opened, a trustee must try to 146 | contact the maintainer(s), primarily by e-mail to try and 147 | resolve things without needing to force anything. They must 148 | record in the ticket when they first tried to contact the 149 | maintainer(s). This documents the start of the 2-week deadline. 150 | (Many users do not have github notifications set up.) 151 | 4. (Trustee) After a week if there's still no contact with any of 152 | the maintainers then a trustee should again email the 153 | maintainers to inform them of the plan to do a NMU, what, why 154 | and when. The when is at earliest in a week. The trustee must 155 | record in the ticket when again tried to contact the 156 | maintainer(s). This documents the start of the 1-week deadline. 157 | 5. (Anyone) Discuss exactly what code needs to be changed. 158 | 6. (Trustee) Fork the upstream repo under the [hackage-trustee 159 | organisation](https://github.com/hackage-trustees) on github and prepare the patches (perhaps by 160 | pulling in changes from somewhere else), including a tag. 161 | 7. (Trustee) Get at least a second trustee to look at and agree to 162 | the changes for the proposed NMU. 163 | 8. (Admin) After the deadline (no sooner than 2 weeks from the 164 | original contact attempt and no sooner than 1 week from the 165 | contact attempt where the intention to do a NMU is explained), 166 | and having got signoff from two trustees, an admin may grant the 167 | trustees authority to make uploads for the package in question. 168 | 9. (Trustee) Tag the version to be uploaded. Do the NMU. Again 169 | inform the maintainers about what has happened and where they 170 | can see the changes that have been made (ie the forked repo and 171 | the ticket tracking the issue). 172 | 173 | ## 4. Full transfer of ownership 174 | 175 | The policy for this is already established, but the trustees can help 176 | facilitate it, e.g. by acting as a point of contact for the procedure. 177 | 178 | This is detailed on the [haskell wiki](https://wiki.haskell.org/Taking_over_a_package). 179 | 180 | ## Anticipated Hackage enhancements for automation 181 | 182 | Edits to .cabal metadata should be emailed to the members of the 183 | maintainer group. Ideally this should include: 184 | 185 | * an English language description of the change, much like the 186 | revisions page on the website 187 | * a patch attachment or link to a patch in a suitable format (e.g. 188 | git patch format) 189 | * instructions for applying the patch (e.g. git commands) 190 | -------------------------------------------------------------------------------- /revisions-information.md: -------------------------------------------------------------------------------- 1 | # Hackage Metadata Revisions — What They Are, How They Work 2 | 3 | ## What are revisions? 4 | 5 | Package maintainers (as well as Hackage trustees) may provide metadata-revisions to existing package versions. These revisions can be thought of as "updating" the cabal file of a package with new or more current information. However, they do not _actually_ update the file. Tarballs retrieved from Hackage are always as the authors uploaded them. Revision information is tracked explicitly in the Hackage index, and `cabal-install` will chose to prefer the latest revision of a cabal file to the original one when downloading or installing a package. 6 | 7 | ## Why do we have revisions? 8 | 9 | Revisions are used to provide better metadata, typically in the case when a build-plan turns out to be incorrect, and we wish to tighten bounds to exclude incompatible versions of dependencies, or when a new version of a package is released and loosening dependencies will allow existing packages to work with it. Strategies for managing revisions and their costs are enumerated in [the hackage trustee cookbook](https://github.com/haskell-infra/hackage-trustees/blob/master/cookbook.md#best-practice-for-managing-meta-data) 10 | 11 | Revisions can also be used when a package homepage or maintainer or the like changes, to keep information displayed current. 12 | 13 | ## Why not just keep uploading new versions? 14 | 15 | First, uploading a whole bunch of code when only metadata changes leads to an unnecessary growth in versions. Second, often revisions need to be applied not only to the most recent version of a package, but prior versions as well. In particular, if a package at a given version has a bad install plan, then you do not want to let some tool continue to think this is a good plan, even if that package is not the latest version. 16 | 17 | ## Where can I see revisions? 18 | 19 | Packages with revisions will tell you so on their Hackage page. You can always access the revisions of a package by appending `/revisions` to its url, like so: http://hackage.haskell.org/package/lens-3.5.1/revisions/ 20 | 21 | ## How can I revise a package? 22 | 23 | On the page of the package (`https://hackage.haskell.org/package/some-package-0.0.1`), you'll find the `Maintainer's Corner` with a link to `edit package information`. After clicking on that link and signing in with your hackage credentials, you can edit the cabal file, 24 | review changes, and upload the revision. 25 | 26 | ## How can I download a package without revisions applied? 27 | 28 | `cabal get --pristine` or simply get `https://hackage.haskell.org/package/foo-1.6.0.0/foo-1.6.0.0.tar.gz` 29 | 30 | ## How can I fix dependencies in the face of potential future revisions? 31 | 32 | If you produced something at a particular point in time and want to pin it down so that no future revisions can alter anything about it, you can specify the `index-state` parameter (either in a configuration file or on the command line) as documented in [the cabal manual: index-state configuration field](http://cabal.readthedocs.io/en/latest/nix-local-build.html?highlight=index-state#cfg-field-index-state) 33 | 34 | This pins down the view of the package universe to use revisions as of any particular timestamp and so allows you to `cabal freeze` not only versions, but the exact revisions of them. 35 | 36 | ## How are revisions numbered? 37 | 38 | The initial upload of a package has the implicit revision zero. Every successive revision increments that by one. 39 | 40 | ## What can revisions change? 41 | 42 | Revisions are intended to only update metadata used by build tooling, or that is used purely for display purposes. The source code of a package is never changed, only specified fields of cabal files. Given the same fixed dependencies and flag configuration, as long as a metadata change hasn't disallowed them, the build product from a compiler in the same environment is intended to be the same regardless of revision changes. Put another way, it is intended revisions do not alter the semantic meaning of the version assigned to a package. 43 | 44 | Specifically, revisions can alter the following: 45 | 46 | * Dependency bounds (tightening or loosening) 47 | * Cabal spec version (only between the interval 1.10 and 1.21) 48 | * Custom-setup dependencies (adding, removing or altering bounds) 49 | * Flag defaults 50 | * Flag type (automatic to manual only) 51 | * Flag descriptions 52 | * Dependencies (adding, but only in very special cases, see below). 53 | * Copyright attribution 54 | * Maintainer attribution 55 | * Author attribution 56 | * Tested-with information 57 | * Bug report URL 58 | * Homepage URL 59 | * Source repositories 60 | * Package synopsis 61 | * Package description 62 | * Package category 63 | 64 | Revisions can also add custom-setup stanzas. This is necessary because newer cabal library versions make explicit custom-setup depends, while in older versions `Setup.hs` had access to whatever happened to be registered in the global and user package databases. This was fragile and created a situation with untracked dependencies (cf: https://www.well-typed.com/blog/2015/07/cabal-setup-deps/) 65 | 66 | Other exceptions for adding dependencies all fall in the camp of needing to add things which had been implicitly assumed in the past, from a small whitelist. Package dependencies which may be added are "base" and "base-orphans". Build tool dependencies which may be added are "alex", "c2hs", "cpphs", "greencard", "happy" and "hsc2hs". This can be seen as improving compatibility with newer cabal library versions which require that past implicit assumptions be made more explicit (cf: https://www.well-typed.com/blog/2015/03/qualified-goals/). 67 | 68 | ## What can't revisions change? 69 | 70 | Revisions can't change anything else. In particular, they cannot alter code, and cannot alter anything besides the cabal file. Among some specific things revisions _cannot_ alter are: 71 | 72 | * Dependencies (removing) 73 | * Dependencies (adding, except as above) 74 | * Package name 75 | * Package version 76 | * Package license 77 | * Build-type 78 | * Modules 79 | * Flags (adding or removing) 80 | * library, sub-library, executable, test-suite, or foreign-library stanzas (adding or removing) 81 | 82 | ## Will these rules for what can and can't be revised ever change? 83 | 84 | It is expected that the overriding goal that revisions do not alter the semantic meaning of the version assigned to a package should always hold. However, it is possible that specific allowances may be made for particular other things to be changed by revisions, in order to keep things building under new cabal library versions. However, as cabal has increasingly made more dependencies explicit (and particular enabled the tracking of cabal specification versioning information itself), then it is hoped that this will occur less frequently going forward, and it is hoped that it should not occur at all. Additionally, as new stanzas and features are added to cabal files over time, their interactions with revisions will also need to be specified. 85 | 86 | ## Why can't I revise licenses? 87 | 88 | Because once code is released under a license, it remains under that license. Additionally a `LICENSE` file is included in the tarball, and revisions can only alter cabal metadata, so the file itself would remain, regardless. 89 | 90 | ## When will Hackage Trustees make revisions? 91 | 92 | In general, it is better if authors make revisions themselves to packages. Trustees are expected to step in to help out when maintainers aren't proactive about these changes, or otherwise when they can offer particular help with regards to improving the health of the package collection as a whole, and they are expected to do so in a way which fosters a good relationship between authors/maintainers and trustees. More specific details are provided in the "metadata-only" sections of the trustee policies: https://github.com/haskell-infra/hackage-trustees/blob/master/policy.md 93 | --------------------------------------------------------------------------------