Merge pull request #1080 from pjf/policy

CKAN policy documents

policy/README.md

@@ -0,0 +1,11 @@
+# CKAN policy documents
+
+These exist here and not in the wiki so that:
+
+- We can more easily track changes.
+- We can ensure there's peer review before merging.
+
+Right now we have policies on the following:
+
+- [Changing our version comparsion routine](version-comparison.md)
+- [De-indexing mods from the CKAN](de-indexing.md)

policy/de-indexing.md

@@ -0,0 +1,12 @@
+# De-indexing mods from the CKAN
+
+From time to time mod authors ask their works be removed from the CKAN. Whether or not we should do this is a matter of licensing and public good. Our policy is based on two simple principles:
+
+1. **The CKAN, like the legal system, takes licenses very seriously.**
+1. **The CKAN acts in the interests of its users.**
+
+Restrictive licenses, including the default "All Rights Reserved", allow the content author absolute control over what happens to their work. **If an All Rights Reserved or other restrictive license author asks for their mod to be de-indexed, we do so promptly and without question.**
+
+Permissive licenses—which includes *every* license the CKAN is aware of that's not marked `restricted` or `unknown`, and includes the popular Creative Commons family of licenses—provide *explicit and irrevocable* permission to use and redistribute the content. Such a license is a strong, *legally binding* promise that the author cannot stop others from reproducing their work. One of the *primary purposes* of such a license is protection against the mod author changing their mind, or imposing further restrictions at a later date.
+
+When an author gives us explicit and irrevocable permission via a legal document to redistribute their work, we cannot in good faith de-index the mod and still act in the interests of our users. **Whenever possible, mods with permissive licenses will be preserved by the CKAN**, especially when alternate downloads to such mods exist, including those cached by the CKAN's own automated systems.

policy/version-comparison.md

@@ -0,0 +1,31 @@
+# Changing our version comparsion routine
+
+(Originally posted as [issue #963](https://github.com/KSP-CKAN/CKAN/issues/963))
+
+It seems that a day doesn't go past when I don't have to explain why changing versions is *hard*, so I'm going to do that here. I'm also going to make us a nice policy folder where things like this can go, so we've got something that's easy to refer to, but also undergoes peer review before changing.
+
+So, why can't we change how we do version comparisons?
+
+## It can break existing mods
+
+We index more than 700 mods, and have more than 2,500 releases indexed. Of those, we've only had a fraction where the Debian versioning spec has not worked. Changing the versioning implementation runs a very real risk of breaking existing mods, and nobody seems to submit the changes along with a proof that all 2,500+ existing documents won't be adversely affected.
+
+## It's almost never needed.
+
+The netkan pre-processor now has additional options for post-processing of versions into standard forms, or bumping the epoch when versions are truly wacky. These come with no risk of breaking existing mods, because we can simply apply them as-needed. In particular, we have:
+
+* `x_netkan_force_v` - Force a friggin' `v` onto the start of the version string.
+* `x_netkan_epoch` - Force a friggin' epoch string onto the front of the version.
+
+OMG, a mod is missing a v? Use the first of these options.
+OMG, a mod went backwards in its order (it's happened), named a version after what the author had for breakfast (it will happen), or completely changed how they do versioning? Use the second.
+
+Seriously. Adjusting how we generate metadata for a couple of mods means we're backwards compatible with all extant clients, and comes with a *much* smaller risk profile.
+
+## Changing versioning schemes is much harder than everyone seems to think.
+
+If we spot a document implementing the old existing spec (v1.6 at time of writing), then we should use the current versioning scheme. If we spot a document with the "new" spec (whatever it is you propose), then we should use the new versioning scheme. Holy fark, does that mean we need *two* implementations of the versioning scheme in clients? Yes, it does. Does that make things twice as complex as it currently is? You bet! Does that mean we're likely to see MORE bugs reported? I think so! And what happens when we need to compare an old version to a new version? We cry, that's what.
+
+The only time we can get away with not doing this is if the versioning scheme compares *all* existing documents the same (yes, all 2,500+ of them). Nobody suggests this, because all the suggestions seem to be about *changing* how versions work, rather than extending it. Even if we did this, we'd have to bump our spec version for all new metadata to make sure old clients don't try to use the new spec format.
+
+**TL;DR:** We're not changing the friggin' spec just because your favourite mod has inconsistent versions. Use the netkan options instead.