summaryrefslogtreecommitdiff
path: root/doc/forum/upgrading_to_propellor_3.0.mdwn
diff options
context:
space:
mode:
authorJoey Hess2016-03-30 22:41:03 -0400
committerJoey Hess2016-03-30 22:41:03 -0400
commit351c06951753e38ddb238d9dca01f29ddef33eeb (patch)
treed95b5fb09ce7ba2267138be5e010243abef217b8 /doc/forum/upgrading_to_propellor_3.0.mdwn
parent29ba1c9a85d81b6b19800a471fed1beb9880b4c5 (diff)
upgrade guide
Diffstat (limited to 'doc/forum/upgrading_to_propellor_3.0.mdwn')
-rw-r--r--doc/forum/upgrading_to_propellor_3.0.mdwn72
1 files changed, 72 insertions, 0 deletions
diff --git a/doc/forum/upgrading_to_propellor_3.0.mdwn b/doc/forum/upgrading_to_propellor_3.0.mdwn
new file mode 100644
index 00000000..af54e938
--- /dev/null
+++ b/doc/forum/upgrading_to_propellor_3.0.mdwn
@@ -0,0 +1,72 @@
+Propellor 3.0 is a major new version with large changes to the API.
+
+Property types have been improved to indicate what systems they target.
+This prevents using eg, Property FreeBSD on a Debian system.
+
+This forum topic is to help users with the upgrade. Post comments
+if you're having trouble and [[Joey]] will get back to you. ;)
+
+First things first: In order to upgrade to propellor 3.0, you **must first
+upgrade to propellor 2.17.2**, and deploy that to all your hosts. If you
+skip this step, propellor --spin will fail when you upgrade to propellor
+3.0.0.
+(Workaround: ssh to host, cd /usr/local/propellor && make clean,
+then you can re-run propellor --spin.)
+[[details_of_why_this_two_step_upgrade_is_needed|todo/problem_with_spin_after_new_dependencies_added]]
+
+Now, the transition guide as far as your config.hs goes:
+
+* Change "host name & foo & bar"
+ to "host name $ props & foo & bar"
+* Similarly, `propertyList` and `combineProperties` need `props`
+ to be used to combine together properties; they no longer accept
+ lists of properties. (If you have such a list, use `toProps`.)
+* And similarly, Chroot, Docker, and Systemd container need `props`
+ to be used to combine together the properies used inside them.
+* The `os` property is removed. Instead use `osDebian`, `osBuntish`,
+ or `osFreeBSD`. These tell the type checker the target OS of a host.
+* GHC needs `{-# LANGUAGE TypeOperators #-}` to use these fancy types.
+ This is enabled by default for all modules in propellor.cabal. But
+ if you are using propellor as a library, you may need to enable it
+ manually.
+
+Additional things you need to do if you've written your own properties:
+
+* Change "Property NoInfo" to "Property UnixLike"
+* Change "Property HasInfo" to "Property (HasInfo + UnixLike)"
+* Change "RevertableProperty NoInfo" to
+ "RevertableProperty UnixLike UnixLike"
+* Change "RevertableProperty HasInfo" to
+ "RevertableProperty (HasInfo + UnixLike) UnixLike"
+* If you know a property only works on a particular OS, like Debian
+ or FreeBSD, use that instead of "UnixLike". For example:
+ "Property Debian"
+* It's also possible make a property support a set of OS's, for example:
+ "Property (Debian + FreeBSD)"
+* Removed `infoProperty` and `simpleProperty` constructors, instead use
+ `property` to construct a Property.
+* Due to the polymorphic type returned by `property`, additional type
+ signatures tend to be needed when using it. For example, this will
+ fail to type check, because the type checker cannot guess what type
+ you intend the intermediate property "go" to have:
+ foo :: Property UnixLike
+ foo = go `requires` bar
+ where
+ go = property "foo" (return NoChange)
+ To fix, specify the type of go:
+ go :: Property UnixLike
+* `ensureProperty` now needs to be passed a witness to the type of the
+ property it's used in.
+ change this: foo = property desc $ ... ensureProperty bar
+ to this: foo = property' desc $ \w -> ... ensureProperty w bar
+* General purpose properties like cmdProperty have type "Property UnixLike".
+ When using that to run a command only available on Debian, you can
+ tighten the type to only the OS that your more specific property works on.
+ For example:
+ upgraded :: Property Debian
+ upgraded = tightenTargets (cmdProperty "apt-get" ["upgrade"])
+* Several utility functions have been renamed:
+ getInfo to fromInfo
+ propertyInfo to getInfo
+ propertyDesc to getDesc
+ propertyChildren to getChildren