Install from source: pin and checkout

Author: ksuess

docs/install/source-step-by-step.md

@@ -242,7 +242,7 @@ plone.api>=2.0.0a3
 Unfortunatly pip does not allow this way of overwriting constraints. 
 
 `mxdev` is made for assembling Plone constraints with your needs of version pinning or source checkouts.\
-It reads your {file}`constraints.txt`, fetches the constraints of Plone and writes a {file}`constraints-mxdev.txt` which combines the constraints. Comments on which Plone constraint is modified asure the readability.
+It reads your {file}`constraints.txt`, fetches the constraints of Plone and writes a {file}`constraints-mxdev.txt` which combines the constraints. Comments on which Plone constraint is modified assure the readability.
 % TODO language: 'readability'?
 
 mxdev operates on three files to tell pip which packages to install with which version.

docs/install/source.md

@@ -180,33 +180,73 @@ pip install -r requirements.txt
 We could now build and run Zope / Plone with one command `make run`.
 
 
+### Checkout add-on
+
+TODO checkout an add-on for development
+
+
 ### Pin a Plone package to a higher version
 
 % TODO describe how to modify constraints of Plone
 
+If you  want to override the constraints of Plone, this section is for you.
+
+Pin the version of a Plone package in {file}`mx.ini`:
 
+```ini
+[settings]
+# constraints of Plone packages
+version-overrides =
+    plone.api>=2.0.0a3
+```
 
-### Checkout a Plone package or add-on
+Apply the changes and install the package with the modified version with:
+
+```shell
+make install
+```
+
+Under the hood happens a creation of a new constraints file and an installation with pip. See the step-by-step chapter for more info: {ref}`install-source-checkout-and-pin`.
+
+Et voilà. Zope can be restarted with `make run`.
+
+
+### Checkout a Plone package
 
 % TODO describe how to checkout packages (Plone package or add-on)
 
-### Build and start your instance
+If you want to checkout a Plone package (not add-on) for development, this section is for you.
 
-We can now build and run Zope / Plone with one command:
+Add the Plone package you want to checkout in {file}`mx.ini`.
 
-```shell
-make run
+```ini
+[plone.restapi]
+url = [email protected]:plone/plone.restapi.git
+branch = master
+extras = test
 ```
 
-Head over to http://localhost:8080/ and see that Plone is running.\
-You can now [create a Plone instance](install-source-create-plone-site-label) and enable the add-on `my.awesome.addon` in {guilabel}`Site Setup` [http://localhost:8080/Plone/prefs_install_products_form](http://localhost:8080/Plone/prefs_install_products_form).
+Apply the changes and install the package with the modified version with:
 
+```shell
+make install
+```
 
+Under the hood happens a creation of a new constraints file and an installation with pip. See the step-by-step chapter for more info: {ref}`install-source-checkout-and-pin`.
 
+Et voilà. Zope can be restarted with `make run`.
 
 
+### Build and start your instance
 
+We can now build and run Zope / Plone with one command:
 
+```shell
+make run
+```
+
+Head over to http://localhost:8080/ and see that Plone is running.\
+You can now [create a Plone instance](install-source-create-plone-site-label) and enable the add-on `my.awesome.addon` in {guilabel}`Site Setup` [http://localhost:8080/Plone/prefs_install_products_form](http://localhost:8080/Plone/prefs_install_products_form).