[Hackage] #508: user guide should document new fields with the version of Cabal they appeared in

[Hackage]

#508: user guide should document new fields with the version of Cabal they
appeared in
------------------------------+---------------------------------------------
  Reporter:  duncan           |        Owner:     
      Type:  enhancement      |       Status:  new
  Priority:  normal           |    Milestone:     
 Component:  Cabal library    |      Version:     
  Severity:  normal           |     Keywords:     
Difficulty:  easy (<4 hours)  |   Ghcversion:     
  Platform:                   |  
------------------------------+---------------------------------------------
 It would be nice if the user guide specified in which Cabal version a
 field was first introduced. This would help package authors work out
 compatibility.

 With this documented we should also check that `cabal check` gives the
 same advice. That is if a package uses a field that is new in version 1.2
 say, that `cabal check` warns if the `cabal-version: >=x.y` number is not
 high enough. It should only be a warning not an error because older Cabal
 versions only warn about unknown fields.

 While we're at it, we should document in the user guide that unknown
 fields give a warning, but should not cause a parse error. This lets
 people use new non-essential informational fields without having to
 absolutely require a later Cabal version. Probably a section on version
 compatibility is wanted.

-- 
Ticket URL: <http://hackage.haskell.org/trac/hackage/ticket/508>
Hackage <http://haskell.org/cabal/>
Hackage: Cabal and related projects