improve usage instructions and GitHub actions

.github/workflows/melpazoid.yml

@@ -0,0 +1,29 @@
+# melpazoid <https://github.com/riscy/melpazoid> build checks.
+
+# If your package is on GitHub, enable melpazoid's checks by copying this file
+# to .github/workflows/melpazoid.yml and modifying RECIPE and EXIST_OK below.
+
+name: melpazoid
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.6
+      uses: actions/setup-python@v1
+      with: { python-version: 3.6 }
+    - name: Install
+      run: |
+        python -m pip install --upgrade pip
+        sudo apt-get install emacs && emacs --version
+        git clone https://github.com/riscy/melpazoid.git ~/melpazoid
+        pip install ~/melpazoid
+    - name: Run
+      env:
+        # RECIPE is your recipe as written for MELPA:
+        RECIPE: (shx :repo "riscy/shx-for-emacs" :fetcher github)
+        # set this to false (or remove it) if the package isn't on MELPA:
+        EXIST_OK: true
+      run: echo $EXIST_OK && make -C ~/melpazoid

.github/workflows/test.yml

@@ -1,3 +1,4 @@
+name: test
 on: [push, pull_request]
 
 jobs:

README.org

@@ -29,55 +29,62 @@ The license checker (4) is currently very crude. The elisp checks (5) are not
 foolproof, sometimes opinionated, and may raise false positives.
 
 * Usage
-  You can [[https://github.com/riscy/melpazoid#fork-it-and-let-ci-do-the-work][fork it and let Travis-CI do the work]], or [[https://github.com/riscy/melpazoid#use-it-locally][use it locally]].
-** Fork it and let Travis-CI do the work
-   If you don't want to install this software or its dependencies, you are
-   encouraged to fork this repository and let CI do the work. Then enable
-   [[https://travis-ci.org][Travis-CI]] on your fork, or just open a pull request against this repository
-   (I won't merge it). The eventual build information will report any issues.
-
-   Your fork will need to point to the Emacs package you want to build, which
-   can be done by modifying the [[https://github.com/riscy/melpazoid/blob/master/.travis.yml#L6][.travis.yml]] file in one of the following ways.
-*** Test a recipe before you even open a pull request to MELPA
-    Modify the ~env~ field and specify your clone URL and your recipe:
-    #+begin_src yaml
-    env:
-    - RECIPE='(my-package :repo "me/my-package-repo" :fetcher github)'
+  The best way to use melpazoid is to add it to your CI (GitHub actions,
+  Travis, etc.), but you can also use it locally.
+** Add it to GitHub actions
+   The very easiest is if your package is hosted on GitHub. Just run the
+   following from your project root:
+   #+begin_src bash
+   mkdir -p .github/workflows
+   curl -o .github/workflows/melpazoid.yml \
+     https://raw.githubusercontent.com/riscy/melpazoid/master/.github/workflows/melpazoid.yml
    #+end_src
-    Note the apostrophes around the RECIPE.
-*** Test a MELPA pull request you've already opened
-    Modify the ~env~ field and specify your open MELPA PR:
+   then edit the file (~.github/workflows/melpazoid.yml~) and change the values
+   of ~RECIPE~ and ~EXIST_OK~ to fit.  Instructions are in the file.
+** Add it to a Travis build
+   If you use Travis, the following is an example ~.travis.yml~ that runs
+   melpazoid on a recipe:
    #+begin_src yaml
+   language: python
+   python: ['3.6']
+   install:
+     - git clone https://github.com/riscy/melpazoid.git ~/melpazoid
+     - pip install ~/melpazoid
    env:
-    - MELPA_PR_URL=https://github.com/melpa/melpa/pull/6713
+     # NOTE: set EXIST_OK to false if the package is not yet on MELPA:
+     - RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github)' EXIST_OK=true
+   script:
+     - make -C ~/melpazoid
    #+end_src
+   remembering to modify ~RECIPE~ and ~EXIST_OK~ accordingly.
 ** Use it locally
    You will need Python ≥ 3.6 (and the ~requests~ package) and Docker. An image
    will be built with (hopefully) all of your requirements installed. By
    default, it will be run with no network access. The output scroll will report
    any discovered issues.
-*** Test the recipe for a hosted package
+*** Test an open MELPA PR
+    If you've already opened a PR against MELPA you can use:
+    #+begin_src bash
+    MELPA_PR_URL=https://github.com/melpa/melpa/pull/6718 make
+    #+end_src
+*** Test a recipe
     #+begin_src bash
     RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github)' make
     #+end_src
-    Note the apostrophes around the RECIPE.  Or test a specific branch:
+    Note the apostrophes around the RECIPE. You can also test a specific branch:
     #+begin_src bash
     RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github :branch "develop")' make
     #+end_src
-*** Test the recipe for a package on your machine
+*** Test a recipe for a package on your machine
     #+begin_src bash
     RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github)' \
         LOCAL_REPO='~/my-emacs-packages/shx-for-emacs' make
     #+end_src
     Instead of cloning from ~riscy/shx-for-emacs~ in this example, melpazoid
     will use the files in ~LOCAL_REPO~.
-*** Test an open MELPA PR
-    #+begin_src bash
-    MELPA_PR_URL=https://github.com/melpa/melpa/pull/6718 make
-    #+end_src
 *** Run in an unending loop
     This currently only works in macOS; it monitors the clipboard
-    for new MELPA PR's, then automatically runs the checks on them.
+    for MELPA PR's, then automatically runs the checks.
     #+begin_src bash
     make
     #+end_src

melpazoid/melpazoid.py

@@ -486,7 +486,9 @@ def print_related_packages(recipe: str):
     for name in known_names[:10]:
         if name != package_name:
             print(f"- {name} {known_packages[name]}")
-    if package_name in known_packages and 'EXIST_OK' not in os.environ:
+    if package_name not in known_packages:
+        return
+    if os.environ.get('EXIST_OK', '').lower() != 'true':
         _fail(f"- '{package_name}' already exists: {known_packages[package_name]}")