Merge pull request RasaHQ#5633 from RasaHQ/readme-poetry-update

Add more information about the usage of Poetry and merge conflict resolution in the lockfile of Poetry to `README.md`

Author: alwx

.github/workflows/continous-integration.yml

@@ -177,6 +177,16 @@ jobs:
     - name: Checkout git repository 🕝
       uses: actions/checkout@v2
 
+    - name: Free disk space
+      # tries to make sure we do not run out of disk space, see
+      # https://github.community/t5/GitHub-Actions/BUG-Strange-quot-No-space-left-on-device-quot-IOExceptions-on/td-p/46101
+      run: |
+        sudo swapoff -a
+        sudo rm -f /swapfile
+        sudo apt clean
+        docker rmi $(docker image ls -aq)
+        df -h
+
     - name: Login to DockerHub Registry 🔢
       run: echo ${{ secrets.DOCKERHUB_PASSWORD }} | docker login -u ${{ env.DOCKERHUB_USERNAME }} --password-stdin || true
 

README.md

@@ -95,33 +95,64 @@ also be asked to sign a
 
 ## Development Internals
 
-### Building from source
+### Installing Poetry
 
 Rasa uses Poetry for packaging and dependency management. If you want to build it from source,
 you have to install Poetry first. This is how it can be done:
 
-```
-curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python3
+```bash
+curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
 ```
 
 There are several other ways to install Poetry. Please, follow 
 [the official guide](https://python-poetry.org/docs/#installation) to see all possible options.
 
-To install dependencies and `rasa` itself in editable mode execute
+### Managing environments
+
+The official [Poetry guide](https://python-poetry.org/docs/managing-environments/) suggests to use
+[pyenv](https://github.com/pyenv/pyenv) or any other similar tool to easily switch between Python versions. 
+This is how it can be done:
+
+```bash
+pyenv install 3.7.6
+pyenv local 3.7.6  # Activate Python 3.7.6 for the current project
+```
+
+By default, Poetry will try to use the currently activated Python version to create the virtual environment 
+for the current project automatically. You can also create and activate a virtual environment manually — in this
+case, Poetry should pick it up and use it to install the dependencies. For example:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+You can make sure that the environment is picked up by executing 
+
+```bash
+poetry env info
 ```
+
+### Building from source
+
+To install dependencies and `rasa` itself in editable mode execute
+
+```bash
 make install
 ```
 
 ### Running and changing the documentation
 
 First of all, install all the required dependencies:
-```
+
+```bash
 make install
 ```
 
 After the installation has finished, you can run and view the documentation
 locally using:
-```
+
+```bash
 make livedocs
 ```
 
@@ -130,25 +161,46 @@ You can now change the docs locally and the web page will automatically reload
 and apply your changes.
 
 ### Running the Tests
+
 In order to run the tests, make sure that you have the development requirements installed:
+
 ```bash
 export PIP_USE_PEP517=false
 make prepare-tests-ubuntu # Only on Ubuntu and Debian based systems
 make prepare-tests-macos  # Only on macOS
 ```
 
 Then, run the tests:
+
 ```bash
 make test
 ```
 
 They can also be run at multiple jobs to save some time:
+
 ```bash
 JOBS=[n] make test
 ```
 
 Where `[n]` is the number of jobs desired. If omitted, `[n]` will be automatically chosen by pytest.
 
+### Resolving merge conflicts
+
+Poetry doesn't include any solution that can help to resolve merge conflicts in
+the lock file `poetry.lock` by default.
+However, there is a great tool called [poetry-merge-lock](https://poetry-merge-lock.readthedocs.io/en/latest/).
+Here is how use can install it:
+
+```bash
+pip install poetry-merge-lock
+```
+
+Just execute this command to resolve merge conflicts in `poetry.lock` automatically:
+
+```bash
+poetry-merge-lock
+```
+
 ### Steps to release a new version
 Releasing a new version is quite simple, as the packages are build and distributed by GitHub Actions.
 

changelog/5633.misc.rst

@@ -0,0 +1,2 @@
+Add more information about the usage of Poetry and the process of merge conflict resolution
+in the lockfile of Poetry to `README.md`.