bump CI scripts and readme

.github/workflows/main.yml

@@ -3,15 +3,18 @@
 name: CI
 on: [push]
 
+env:
+  # useful for scripts & sometimes tests to know
+  CI: true
+
 jobs:
   build:
-    runs-on: ubuntu-latest
-
     strategy:
       matrix:
+        platform: [ubuntu-latest] # macos-latest, windows-latest??
         python-version: [3.6, 3.7, 3.8]
-    # TODO shit. matrix is going to prevent from twine deployments because of version conflicts??
-    # add 'and' clause??
+
+    runs-on: ${{ matrix.platform }}
 
     steps:
     # fuck me. https://help.github.com/en/actions/reference/workflow-commands-for-github-actions#adding-a-system-path
@@ -32,7 +35,7 @@ jobs:
 
   pypi:
     runs-on: ubuntu-latest
-    needs: build
+    needs: [build] # add all other jobs here
 
     steps:
     - run: echo "::add-path::$HOME/.local/bin"

README.org

@@ -2,13 +2,15 @@
 
 Orger converts your data into Org-mode to allow for quick access and search.
 
-I write in detail about usecases and motivation for it [[https://beepb00p.xyz/orger.html][here]], this readme is setup manual for the most part!
+I write in detail about usecases and motivation for it [[https://beepb00p.xyz/orger.html][here]], this readme is mostly the setup manual!
 
 * Installing
 
 [[https://pypi.org/project/orger][PyPi]]: ~pip3 install --user orger~
 
 * Usage and examples
+There are several examples [[https://beepb00p.xyz/orger.html#examples][here]], including a [[https://www.youtube.com/watch?v=ib_PDJpTh-Q][screencast]].
+
 See [[./modules/pocket_demo.py][pocket_demo]] for a documented literate demo and [[./modules][modules]] for some of modules I'm using.
 
 Here's a quick minimalistic demo.

scripts/ci/run

@@ -3,7 +3,25 @@
 cd "$(dirname "$0")"
 cd ../..
 
+if ! command -v sudo; then
+    # CI or Docker sometimes doesn't have it, so useful to have a dummy
+    function sudo {
+        "$@"
+    }
+fi
+
+if ! [ -z "$CI" ]; then
+    # install OS specific stuff here
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        # macos
+        :
+    else
+        :
+    fi
+fi
+
 # vim is used in one of the tests
-which vim || sudo apt install vim
+command -v vim || sudo apt install vim
+
 pip3 install --user tox
 tox

scripts/release

@@ -1,10 +1,25 @@
 #!/usr/bin/env python3
+'''
+Run [[file:scripts/release][scripts/release]] to deploy Python package onto [[https://pypi.org][PyPi]] and [[https://test.pypi.org][test PyPi]].
+
+The script expects =TWINE_PASSWORD= environment variable to contain the [[https://pypi.org/help/#apitoken][PyPi token]] (not the password!).
+
+The script can be run manually.
+It's also running as =pypi= job in [[file:.github/workflows/main.yml][Github Actions config]]. Packages are deployed on:
+- every master commit, onto test pypi
+- every new tag, onto production pypi
+
+You'll need to set =TWINE_PASSWORD= and =TWINE_PASSWORD_TEST= in [[https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets][secrets]]
+for Github Actions deployment to work.
+'''
+
 import os
 import sys
 from pathlib import Path
 from subprocess import check_call
 import shutil
 
+is_ci = os.environ.get('CI') is not None
 
 def main():
     import argparse
@@ -19,6 +34,10 @@ def main():
     root = Path(__file__).absolute().parent.parent
     os.chdir(root) # just in case
 
+    if is_ci:
+        # see https://github.com/actions/checkout/issues/217
+        check_call('git fetch --prune --unshallow'.split())
+
     dist = root / 'dist'
     if dist.exists():
         shutil.rmtree(dist)