Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modify upload guidelines as per the uncurated hackage proposal #676

Merged
merged 11 commits into from
Mar 19, 2018
Merged

Modify upload guidelines as per the uncurated hackage proposal #676

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
3d6e452
Modify upload guidelines as per the uncurated hackage proposal
gbaz Feb 19, 2018
64a59af
Update upload.html.st
gbaz Feb 19, 2018
11151c8
Update index.html.st
gbaz Feb 19, 2018
77e879c
Update index.html.st
gbaz Feb 19, 2018
9d34274
Update index.html.st
gbaz Feb 19, 2018
fb9c542
Update upload.html.st
gbaz Feb 19, 2018
3ceca5e
add transitive property wording
gbaz Mar 16, 2018
2446cad
Implement @phadej's feedback
hvr Mar 18, 2018
22119d2
Try to emphasize the importance of the transitive contractual property
hvr Mar 18, 2018
5408ced
Merge branch 'central-server' into gbaz-uncurated-guidelines
gbaz Mar 19, 2018
ddddf02
Update index.html.st
gbaz Mar 19, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions datafiles/templates/index.html.st
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,10 @@ $hackagePageHeader()$
</ul>
<p>Guidelines for Hackage Packages:</p>
<ul>
<li>All packages <abbr title="[RFC2119] The word 'should' is intended to denote that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course">should</abbr> follow the <a href="https://pvp.haskell.org/">Package Versioning Policy (PVP)</a>.</li>
<li><strong>Packages cannot be deleted</strong>, so you should consider uploading new versions packages as a <a href="/packages/candidates/upload">package candidate</a> and testing before publishing it to the main index.</li>
<li>Please consult the <a href="/upload">documentation for uploading packages</a> for more in-depth information about Hackage's policies.</li>
<li><strong>Packages cannot be deleted</strong>, so you should consider uploading new package versions as <a href="/packages/candidates/upload">package candidates</a> and testing before publishing to the main index.</li>
<li>All <a href="/upload#versioning_and_curation">curated</a> packages <abbr title="[RFC2119] The word 'should' is intended to denote that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course">should</abbr> follow the <a href="https://pvp.haskell.org/">Package Versioning Policy (PVP)</a>.</li>
<li>Packages uploads may opt-out of curation through use of the <tt>x-curation</tt> field
<li>Please consult the <a href="/upload">documentation for uploading packages</a> for more in-depth information about Hackage's policies, including the usage of the <tt>x-curation</tt> field.</li>
</ul>
<p>In addition to the main package list page, there are a few other package indices:</p>
<ul>
Expand Down
29 changes: 19 additions & 10 deletions datafiles/templates/upload.html.st
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ $hackagePageHeader()$
<div style="font-size: large; text-align: center;">Upload and publish
a package <strong>permanently</strong>: <a href="/packages/upload">Upload</a></div>

<p>Uploading a package puts it in the <a href="/packages/browse">main package index</a>
<p>Uploading a package puts it in the <a href="/packages/browse">package index</a>
so that anyone can download it and view information about it. <strong>You can only
upload a package version once and this cannot be undone</strong>, so try to get it right the first time!
To reduce the risk of mistakes it's recommended to use the <a href="#candidates">package candidates feature</a> described below.
Expand All @@ -28,13 +28,6 @@ synopsis/description as well as ensuring your package is installable
by helping with providing accurate meta-data.
</p>

<p>In the course of the curation process, the
<a href="/packages/trustees">Hackage Trustees</a> need to be
able to contact you, to inform you about and help you resolve issues with
your package (including its meta-data) which affect the Hackage
ecosystem.
</p>

<p>Packages must be in the form produced by Cabal's
<a href="http://www.haskell.org/cabal/users-guide/installing-packages.html#setup-sdist">sdist</a> command:
a gzipped tar file <em>package</em>-<em>version</em><tt>.tar.gz</tt>
Expand All @@ -43,12 +36,28 @@ of that name and version, including <em>package</em><tt>.cabal</tt>.
See the notes at the bottom of the page.
</p>

<h3>Package versioning</h3>
<h3 id="versioning_and_curation">Package versioning and curation</h3>

<p>In order to ensure the integrity and well-functioning of the Hackage/Cabal ecosystem, all packages <abbr title="[RFC2119] The word 'should' is intended to denote that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course">should</abbr> follow Haskell's <a href="https://pvp.haskell.org/">Package Versioning Policy (PVP)</a>.</p>
<p>By default, uploaded packages are <i>curated</i> which means that both maintainers and hackage trustees may revise their metadata (particularly involving version bounds) to guide build tools in producing install-plans. (For more information on revisions, see the <a href="https://github.com/haskell-infra/hackage-trustees/blob/master/revisions-information.md">FAQ</A>).

<p>In order to ensure the integrity and well-functioning of the Hackage/Cabal ecosystem, all curated packages <abbr title="[RFC2119] The word 'should' is intended to denote that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course">should</abbr> follow Haskell's <a href="https://pvp.haskell.org/">Package Versioning Policy (PVP)</a>.</p>

<p>In particular, be aware that although the <a href="https://pvp.haskell.org/">PVP</a> and <a href="http://semver.org/">SemVer</a> are based on the same concepts they differ significantly in structure and consequently are <em>not compatible</em> with each other. Please consult the <a href="https://pvp.haskell.org/faq/#semver">PVP/SemVer FAQ section</a> for more details about the differences and related issues.</p>

<p>Further, an important property of the PVP contract is that it can only be effective and provide strong enough guarantees if it is followed not only by an individual package, but also by that package's transitive dependencies. Consequently, packages which are curated should aim to depend only on other curated packages.</p>

<p>In the course of the curation process, the
<a href="/packages/trustees">Hackage Trustees</a> need to be
able to contact package maintainers, to inform them about and help to resolve issues with
their packages (including its meta-data) which affect the Hackage
ecosystem.</p>

<p>Package uploaders may choose to exclude individual package uploads from curation, by setting the <tt>x-curation:</tt> field of the package's cabal file to <tt>uncurated</tt>. Packages which are uncurated have no expectations on them regarding versioning policy. Trustees or maintainers may <i>adopt</i> uncurated packages into the curated layer through metadata revisions. Metadata revisions must not set the value of the <tt>x-curation</tt> field to any variant of <tt>uncurated</tt>.</p>

<p>Two variants of the <tt>uncurated</tt> property are supported. First, <tt>uncurated-no-trustee-contact</tt>, which indicates that maintainers do not wish to be contacted by trustees regarding any metadata issues with the package. (Contact may still occur over issues that are not related to curation, such as licensing, etc.). Second, <tt>uncurated-seeking-adoption</tt>, which indicates that maintainers would like their package to be adopted in the curated layer, but currently some issue prevents this, which they would like assistance with.</p>

<p>In the future, metadata regarding curation will be made available in the UI of Hackage, and different derived indexes will be provided for the uncurated and curated layers of packages.</p>

<h3>Open source licenses</h3>

<p>The code and other material you upload and distribute via this site must be
Expand Down