add release.sh script to generate changelog, release to GH and Dockerhub

.circleci/config.yml

@@ -38,6 +38,9 @@ jobs:
             docker push ocrd/all:maximum-git &
             jobs+=($!)
             while sleep 60; ps -p "${jobs[*]}"; do :; done
+      - run:
+          name: Create a date-versioned mirror of ocrd/all:maximum
+          command: bash release.sh release-dockerhub
       - run: curl -X POST "$MICROBADGER_WEBHOOK" || true
 workflows:
   version: 2

.github/contributing.md

@@ -0,0 +1,34 @@
+# ocrd_all Contributing guidelines
+
+For general information on how to use `ocrd_all`, please see the [README](https://github.com/OCR-D/ocrd_all).
+
+Thank you for being interested in contributing to `ocrd_all`!
+
+If you have any questions, feel free to ask them in the [OCR-D gitter chat](https://gitter.im/OCR-D/Lobby).
+
+## How to create PR for updated submodules
+
+1. Create a new branch with any name, e.g. `git checkout -b update-$(date +'%Y-%m-%d')`
+2. Selectively update submodules in a way that makes sense to you. To upgrade
+  all submodules to the latest upstream versions, run `./release.sh update`. To
+  update only a specific submodule, such as `ocrd_cis`, run `./release.sh update
+  ocrd_cis`. Or update individual submodules manually: `cd <submodule>; git pull
+  origin master` (replace `master` if you want to merge another branch instead)
+3. Manually check with `git status` that the changes are consistent with what
+  you want to update in the PR.
+4. `git add` / `git commit`
+5. `git push` to your `ocrd_all` fork on GitHub
+6. Open a new PR for that branch (The `git push` request will show you the right URL)
+
+## How to merge update PR for updated submodules
+
+You need to be a "Maintainer" or "Admin" to merge pull requests.
+
+1. Wait for CI to successfully finish (ensuring that the `maximum` image can be built)
+2. **Do not merge on GitHub**. Do the following locally:
+3. Check out the `master` branch locally, `git pull` to make sure it's up-to-date.
+4. Merge the PR branch with the `--no-commit` flag so the merge commit doesn't hide the changes: `git merge --no-commit pr-branch`
+5. Generate the changelog: `./release.sh changelog`.
+6. Inspect the CHANGELOG.md and remove superfluous information like merge commits or spurious newlines. Copy the new section to the clipboard (see step 8)
+7. Release to GitHub with `./release.sh release-github`. This will take care of comitting, tagging and pushing the release.
+8. Create a new release on GitHub, paste the new changelog section as the release notes.

LICENSE

@@ -1,4 +1,5 @@
 Copyright © 2019 Stefan Weil
+Copyright © 2020 OCR-D/ocrd_all contributors (https://github.com/OCR-D/ocrd_all/graphs/contributors)
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the "Software"),

README.md

@@ -44,6 +44,7 @@ in the current shell environment via PATH and PYTHONHOME.)
     * [No published/recent version on PyPI](#no-publishedrecent-version-on-pypi)
     * [Conflicting requirements](#conflicting-requirements)
     * [System requirements](#system-requirements)
+  * [Contributing](#contributing)
 
 ## Preconditions
 
@@ -387,3 +388,9 @@ Not all modules advertise their system package requirements via `make deps-ubunt
 - `tesseract` (when installing from source not PPA): depends on `libleptonica-dev` etc
 
 _(Solved by maintaining these requirements under `deps-ubuntu` here.)_
+
+## Contributing
+
+Please see our [contributing
+guide](https://github.com/OCR-D/ocrd_all/blob/master/.github/contributing.md)
+to learn how you can support the project.

release.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# set -ex
+
+# SCRIPTDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+# PATH="$SCRIPTDIR:$PATH"
+SCRIPTNAME=$(basename $0)
+
+version=$(git describe --abbrev=0 --tags --exact-match 2>/dev/null||date +'v%Y-%m-%d')
+
+usage () {
+    echo "$SCRIPTNAME [options] <command>"
+    echo ""
+    echo "Options:"
+    echo ""
+    echo "  -V  Version to release. Default: $version"
+    echo "  -h  Show this help"
+    echo ""
+    echo "Commands:"
+    echo ""
+    echo "  update              Update all submodules to most recent master/dev branch"
+    echo "  changelog           Generate a changelog for all modified submodules"
+    echo "  release-github      Release to GitHub as $version"
+    echo "  release-dockerhub   Release ocrd/all:maximum as ocrd/all:${version#v} to DockerHub"
+}
+
+main () {
+    while [[ "$1" = -* ]];do
+        case "$1" in
+            -V) version="$2";
+                if [[ "$version" != v* ]];then
+                    echo "Version must start with 'v': $version"
+                    exit 1
+                fi
+                shift; ;;
+            -h) usage; exit; ;;
+        esac
+        shift
+    done
+    if [[ -z "$1" ]];then
+        usage
+        exit 1
+    fi
+    cmd="$1"
+    shift
+    case "$cmd" in
+        update) update_all_submodules "$@" ;;
+        changelog) update_changelog ;;
+        release-github) release_github ;;
+        release-dockerhub) release_dockerhub ;;
+        *) usage; exit 1 ;;
+    esac
+}
+
+submodule_url () {
+    local sm="$1"
+    git config --file .gitmodules --get-regexp "$sm.url" |cut -d' ' -f 2|sed 's,\.git$,,'
+}
+
+list_all_submodules () {
+    git config --file .gitmodules --get-regexp path | awk '{ print $2 }' |sort -n
+}
+
+list_changed_submodules () {
+    git submodule status |grep '^+'|cut -d ' ' -f 2|sort -n
+}
+
+update_one_submodule () {
+    local sm="$1"
+    local branch="master"
+    if test $sm = 'ocrd_cis';then
+        branch="dev"
+    fi
+    (
+        cd $sm
+        git pull origin "$branch"
+        git pull origin "$branch" --tags
+        git submodule update --init
+     )
+}
+
+update_all_submodules () {
+    if [[ $# -gt 0 ]];then
+        sms="$@"
+    else
+        sms=($(list_all_submodules))
+    fi
+    for sm in "${sms[@]}";do
+        update_one_submodule "$sm"
+    done
+}
+
+submodule_changelog () {
+    local sm="$1"
+    local smurl=$(submodule_url "$sm")
+    local smtag=$(cd $sm; git describe --abbrev=0 --tags 2>/dev/null|| echo '')
+    if [[ -n "$smtag" ]];then
+        smtag="\\n> Release: [$smtag]($smurl/releases/$smtag)\\n"
+    fi
+    git diff --submodule=log "$sm"| sed \
+        -e "s,^Submodule \\([^ ]\\+\\) \\([^\.]\\+\\)..\\([^\.]\\+\\):,### [\1]($smurl) [\2]($smurl/commits\2)..[\3]($smurl/commits/\3)\\n$smtag," \
+        -e 's,^\s*>,  > *,'
+}
+
+update_changelog () {
+    (
+        echo "# Changelog"
+        echo ""
+        echo "## [$version](https://github.com/OCR-D/ocrd_all/releases/$version)"
+        echo ""
+        for sm in $(list_changed_submodules);do
+            submodule_changelog $sm
+            echo ""
+        done
+        sed "/^[#] Changelog/d" CHANGELOG.md
+    ) > CHANGELOG.md.tmp
+    mv CHANGELOG.md.tmp CHANGELOG.md
+}
+
+release_github () {
+    if [[ "$(git status CHANGELOG.md)" = "" ]];then
+        echo "CHANGELOG.md is unmodified. Did you update it?"
+        exit 1
+    fi
+    changelog=$(git diff CHANGELOG.md|grep '^+'|sed -e 's,^.,,' -e 's,",\",g' )
+    git add CHANGELOG.md
+    git commit -m ":package: $version"
+    git tag $version
+    git push
+    git push --tags
+    echo -n "(p)rint changelog, (c)opy changelog to clipboard, (i)gnore? > "
+    read resp;
+    if [[ $resp = p* || $resp = P* ]];then
+        echo "$changelog"
+    elif [[ $resp = c* || $resp = C* ]];then
+        if command -v pbcopy 2>/dev/null;then
+            echo "$changelog" | pbcopy
+            echo "Copied to clipboard"
+        elif command -v xclip 2>/dev/null;then
+            echo "$changelog" | xclip -i
+            echo "Copied to clipboard"
+        else
+            echo "!! Neither xclip nor pbcopy available. Install xclip or pbcopy or copy by hand:"
+            echo "$changelog"
+        fi
+    fi
+}
+
+release_dockerhub () {
+    docker tag ocrd/all:maximum ocrd/all:${version#v}
+    docker push ocrd/all:${version#v}
+}
+
+
+main "$@"