diff --git a/release/README.md b/release/README.md
index 3a0f4620a780d241b9f6ccabe21fff6f18710cb4..1d187774374803749e6b4239e69e0aac7ee46f8a 100644
--- a/release/README.md
+++ b/release/README.md
@@ -1,3 +1,43 @@
+
+Generate changelog
+------------------
+
+To generate a changelog that shows changes (tags and commits) in all packages since last release, please run the following script:
+
+    $ python generate_changelog.py <Gitlab Private Access Token> > changelog_since_last_release.txt
+
+The script will go through all packages listed in https://gitlab.idiap.ch/bob/bob.nightlies/blob/master/order.txt file. The date of the latest tag of `bob` package, will be taken as the last release date. All changes including tags and commits will be logged for each package. The resulted log file should be manually updated, so the changes descriptions become more concise. Once updated, the changelog should be put in https://gitlab.idiap.ch/bob/bob/tags.
+
+Manually update changelog
+-------------------------
+
+The changelog since the last release can be found in `changelog_since_last_release.txt`. The structure is the following:
+
+    * package name
+      * tag1 name (date of the tag). 
+        * tag description. Each line of the tag description starts with `*` character.
+        - commits (from earliest to latest). Each line of the commit starts with `-` character.
+      * tag2 name (date of the tag). 
+        * tag description. Each line of the tag description starts with `*` character.
+        - commits (from earliest to latest). Each line of the commit starts with `-` character.
+      * patch
+        - leftover not-tagged commits (from earliest to latest)
+
+To manually update the changelog, follow these steps:
+
+    1. For each tag, summarize the commits into several descriptive lines. These summaries become
+    tag descriptions and they should extend/update the existing tag description. Therefore, each line 
+    of the summary should also start with `*` character like the tag descriptions.
+    2. The last tag name is called `patch`. This indicates that a patch version of this package will 
+    be automatically updated during the next tag/release. You can change `patch` to `minor` or `major`, 
+    and the package will be then tagged/released with either minor or major version bump. 
+    3. Once all commits were changed to corresponding tag descriptions (no more lines start with `-` characters), 
+    this package is ready for release and you can continue to another package in the changelog. 
+
+
+Release Bob
+-----------
+
 Here are some instructions to do a massive Bob release and scripts to help you
 release Bob:
 
@@ -141,8 +181,7 @@ Run the pipeline for master of bob.conda once and fix till every conda package
 is released.
 
 
-Release `bob`. Here is some code to get the changelog generated automatically
-for bob:
+Release `bob`. 
 
 
     import gitlab
@@ -189,51 +228,3 @@ for bob:
         if max_version != version:
             print(pkg, versions)
 
-Generate the changelog:
-
-    import gitlab
-    import distutils.version
-    import datetime
-    from collections import OrderedDict
-    gl = gitlab.Gitlab.from_config()
-    bob_group = gl.groups.search('bob')[0]
-    path = '.../git/bobs/bob/requirements.txt'
-    pkgs = OrderedDict()
-    for line in open(path):
-        pkg, version = line.split('==')
-        pkgs[pkg.strip()] = version.strip()
-
-    # release date of last Bob release + 1 day
-    last_release = datetime.datetime(2017, 2, 10)
-
-    def get_datetime_from_tag(tag):
-        return datetime.datetime.strptime(tag.commit.committed_date[:-6], '%Y-%m-%dT%H:%M:%S.%f')
-
-    def sort_tags(tags):
-        return sorted(tags, key=lambda x: get_datetime_from_tag(x))
-
-    def get_tag_changelog(tag):
-        try:
-            return tag.release.description
-        except Exception:
-            return ''
-
-    for pkg, version in pkgs.items():
-        projects = bob_group.projects.search(pkg)
-        project = [p for p in projects if p.name == pkg][0]
-        tags = project.tags.list(all=True)
-        # sort tags by date
-        tags = filter(lambda x: get_datetime_from_tag(x) >= last_release, tags)
-        tags = sort_tags(tags)
-        print('* ' + pkg)
-        for tag in tags:
-            print('  * ' + tag.name)
-            for line in get_tag_changelog(tag).split('\r\n'):
-                line = line.strip()
-                line = line.replace('!', pkg+'!')
-                line = line.replace('#', pkg+'#')
-                if not line:
-                    continue
-                print(' '*5 + '* ' + line)
-
-Put this awesome changelog in https://gitlab.idiap.ch/bob/bob/tags