Initial (un)version (#1)

.github/FUNDING.yml

@@ -0,0 +1 @@
+open_collective: ponyc

.github/workflows/announce-a-release.yml

@@ -0,0 +1,22 @@
+name: Announce a release
+
+on:
+  push:
+    tags: announce-*.*.*
+
+jobs:
+  announce-a-release:
+    name: Announce a release
+    runs-on: ubuntu-latest
+    container:
+      image: ponylang/shared-docker-ci-release:20191107
+    steps:
+      - uses: actions/checkout@v1
+      - name: Announce
+        uses: ponylang/[email protected]
+        with:
+          step: announce-a-release
+        env:
+          ASSET_NAME: "main-actor-documentation-action"
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          ZULIP_TOKEN: ${{ secrets.ZULIP_TOKEN }}

.github/workflows/changelog-bot.yml

@@ -0,0 +1,16 @@
+name: Changelog Bot
+
+on: 
+  push:
+    branches:
+      - master
+
+jobs:
+  changelog-bot:
+    runs-on: ubuntu-latest
+    name: Update CHANGELOG.md
+    steps:
+      - name: Update Changelog
+        uses: ponylang/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - \d+.\d+.\d+
+
+jobs:
+  trigger-release-announcement:
+    name: Trigger release announcement
+    runs-on: ubuntu-latest
+    container:
+      image: ponylang/shared-docker-ci-release:20191107
+    steps:
+      - uses: actions/checkout@v1
+      - name: Trigger
+        uses: ponylang/[email protected]
+        with:
+          step: trigger-release-announcement
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}

.github/workflows/start-a-release.yml

@@ -0,0 +1,20 @@
+name: Start a release
+
+on:
+  push:
+    tags: release-*.*.*
+
+jobs:
+  start-a-release:
+    name: Start a release
+    runs-on: ubuntu-latest
+    container:
+      image: ponylang/shared-docker-ci-release:20191107
+    steps:
+      - uses: actions/checkout@v1
+      - name: Start
+        uses: ponylang/[email protected]
+        with:
+          step: start-a-release
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Change Log
+
+All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/) and [Keep a CHANGELOG](http://keepachangelog.com/).
+
+## [unreleased] - unreleased
+
+### Fixed
+
+
+### Added
+
+- Initial version
+
+### Changed
+
+

Dockerfile

@@ -0,0 +1,5 @@
+FROM ponylang/shared-docker-ci-release-a-library:release
+
+COPY entrypoint.sh /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2020, The Pony Developers
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1 +1,42 @@
-# upload-docs-to-main-actor-action
+# main-actor-documentation-action
+
+A GitHub Action that generates documentation for a Pony library and updates that documentation to [main.actor](https://main.actor). The library in question must have a Makefile with a target `docs` that can be used to generate the documentation.
+
+## Example workflow
+
+In **release.yaml**, in addition the usual [release-bot-action](https://github.com/ponylang/release-bot-action) workflow entries.
+
+```yml
+name: Release
+
+on:
+  push:
+    tags:
+      - \d+.\d+.\d+
+
+jobs:
+  generate-documentation:
+    name: Generate documentation for release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Generate documentation and upload
+        uses: ponylang/main-actor-documentation-action@master
+        with:
+          library_name: "MYLIBRARY"
+          docs_build_dir: "docs/build-MYLIBRARY"
+          git_user_name: "Ponylang Main Bot"
+          git_user_email: "[email protected]"
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+```
+
+N.B. The environment variable RELEASE_TOKEN that is required by each step must be a personal access token with at least public_repo access. You can not use the GITHUB_TOKEN environment variable provided by GitHub's action environment. If you try to use GITHUB_TOKEN, the action will fail.
+
+## Additional setup
+
+Any user or organization that intends to use this action must have set up a fork of the [ponylang/main.actor-package-markdown](https://github.com/ponylang/main.actor-package-markdown) repository.
+
+So for example, if your GitHub user name is `JeannieQPublic`, then there needs to be a fork of `main.actor-package-markdown` at `JeannieQPublic/main.actor-package-markdown`.
+
+The personal access token user in the workflow configuration as `RELEASE_TOKEN` must have at least `public_repo` access to the `main.actor-package-markdown` fork.

RELEASE_PROCESS.md

@@ -0,0 +1,41 @@
+# How to cut a main-actor-documentation-action release
+
+This document is aimed at members of the team who might be cutting a release of main-actor-documentation-action. It serves as a checklist that can take you through doing a release step-by-step.
+
+## Prerequisites
+
+* You must have commit access to the main-actor-documentation-action repository.
+
+## Releasing
+
+Please note that this document was written with the assumption that you are using a clone of the `changelog-bot` repo. You have to be using a clone rather than a fork. It is advised to your do this by making a fresh clone of the `main-actor-documentation-action` repo from which you will release.
+
+```bash
+git clone [email protected]:ponylang/main-actor-documentation-action.git main-actor-documentation-action-release-clean
+cd main-actor-documentation-action-release-clean
+```
+
+Before getting started, you will need a number for the version that you will be releasing as well as an agreed upon "golden commit" that will form the basis of the release.
+
+The "golden commit" must be `HEAD` on the `master` branch of this repository. At this time, releasing from any other location is not supported.
+
+For the duration of this document, that we are releasing version is `0.3.1`. Any place you see those values, please substitute your own version.
+
+```bash
+git tag release-0.3.1
+git push origin release-0.3.1
+```
+
+## If something goes wrong
+
+The release process can be restarted at various points in it's life-cycle by pushing specially crafted tags.
+
+## Start a release
+
+As documented above, a release is started by pushing a tag of the form `release-x.y.z`.
+
+## Announce release
+
+The release process can be manually restarted from here by push a tag of the form `announce-x.y.z`. The tag must be on a commit that is after "Release x.y.z" commit that was generated during the `Start a release` portion of the process.
+
+If you need to restart from here, you will need to pull the latest updates from the main-actor-documentation-action repo as it will have changed and the commit you need to tag will not be available in your copy of the repo with pulling.

VERSION

@@ -0,0 +1 @@
+0.0.0

action.yml

@@ -0,0 +1,18 @@
+name: 'main.actor Documentation action'
+description: 'Generates documentation for the release and uploads to main.actor'
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+inputs:
+  library_name:
+    description: 'Name of the library being uploaded'
+    required: true
+  docs_build_dir:
+    description: 'Location, relative to the Makefile, that generated documentation will be placed'
+    required: true
+  git_user_name:
+    description: 'Name to associate with documentation commits'
+    required: true
+  git_user_email:
+    description: 'Email to associate with documentation commits'
+    required: true

entrypoint.sh

@@ -0,0 +1,135 @@
+#!/bin/bash
+
+# Generates documentation for the release and uploads to main.actor
+#
+# Tools required in the environment that runs this:
+#
+# - bash
+# - curl
+# - jq
+# - git
+# - make
+# - ponyc
+# - corral
+
+set -o errexit
+
+# Verify ENV is set up correctly
+# We validate all that need to be set in case, in an absolute emergency,
+# we need to run this by hand. Otherwise the GitHub actions environment should
+# provide all of these if properly configured
+if [[ -z "${RELEASE_TOKEN}" ]]; then
+  echo -e "\e[31mA personal access token needs to be set in RELEASE_TOKEN."
+  echo -e "\e[31mIt should not be secrets.GITHUB_TOKEN. It has to be a"
+  echo -e "\e[31mpersonal access token otherwise next steps in the release"
+  echo -e "\e[31mprocess WILL NOT trigger."
+  echo -e "\e[31mPersonal access tokens are in the form:"
+  echo -e "\e[31m     TOKEN"
+  echo -e "\e[31mfor example:"
+  echo -e "\e[31m     1234567890"
+  echo -e "\e[31mExiting.\e[0m"
+  exit 1
+fi
+
+if [[ -z "${GITHUB_REF}" ]]; then
+  echo -e "\e[31mThe release tag needs to be set in GITHUB_REF."
+  echo -e "\e[31mThe tag should be in the following GitHub specific form:"
+  echo -e "\e[31m    /refs/tags/X.Y.Z"
+  echo -e "\e[31mwhere X.Y.Z is the version we are releasing"
+  echo -e "\e[31mExiting.\e[0m"
+  exit 1
+fi
+
+if [[ -z "${GITHUB_REPOSITORY}" ]]; then
+  echo -e "\e[31mName of this repository needs to be set in GITHUB_REPOSITORY."
+  echo -e "\e[31mShould be in the form OWNER/REPO, for example:"
+  echo -e "\e[31m     ponylang/ponyup"
+  echo -e "\e[31mExiting.\e[0m"
+  exit 1
+fi
+
+# no unset variables allowed from here on out
+# allow above so we can display nice error messages for expected unset variables
+set -o nounset
+
+# Set up GitHub credentials
+git config --global user.name "${INPUT_GIT_USER_NAME}"
+git config --global user.email "${INPUT_GIT_USER_EMAIL}"
+git config --global push.default simple
+
+# Extract version from tag reference
+# Tag ref version: "refs/tags/1.0.0"
+# Version: "1.0.0"
+VERSION="${GITHUB_REF/refs\/tags\//}"
+
+# Directory we are going to do additional work in
+GEN_MD="$(mktemp -d)"
+
+DOCS_DIR="${GEN_MD}/${INPUT_LIBRARY_NAME}/${VERSION}"
+
+# extract owner from GITHUB_REPOSITORY
+IFS="/"
+read -ra SPLIT <<< "${GITHUB_REPOSITORY}"
+REPO_OWNER="${SPLIT[0]}"
+
+echo -e "\e[34mCloning main.actor-package-markdown repo into ${GEN_MD}\e[0m"
+git clone \
+  "https://${RELEASE_TOKEN}@github.com/${REPO_OWNER}/main.actor-package-markdown.git" \
+  "${GEN_MD}"
+
+# Make the docs
+# We make assumptions about the location for the docs
+make docs
+
+# $INPUT_DOCS_BUILD_DIR contains the raw generated markdown for our documentation
+pushd "${INPUT_DOCS_BUILD_DIR}" || exit 1
+mkdir -p "${DOCS_DIR}"
+cp -r docs/* "${DOCS_DIR}"/
+cp -r mkdocs.yml "${DOCS_DIR}"
+
+# Upload any new documentation
+echo -e "\e[34mPreparing to upload generated markdown content from ${GEN_MD}\e[0m"
+echo -e "\e[34mGit fiddling commences...\e[0m"
+pushd "${GEN_MD}" || exit 1
+echo -e "\e[34mCreating a branch for generated documentation...\e[0m"
+branch_name="${INPUT_LIBRARY_NAME}-${VERSION}"
+git checkout -b "${branch_name}"
+echo -e "\e[34mAdding content...\e[0m"
+git add .
+git commit -m "Add docs for package: ${INPUT_LIBRARY_NAME} version: ${VERSION}"
+echo -e "\e[34mUploading new generated markdown content...\e[0m"
+git push --set-upstream origin "${branch_name}"
+echo -e "\e[34mGenerated markdown content has been uploaded!\e[0m"
+popd || exit 1
+
+# Create a PR
+echo -e "\e[34mPreparing to create a pull request...\e[0m"
+jsontemplate="
+{
+  \"title\":\$title,
+  \"head\":\$incoming_repo_and_branch,
+  \"base\":\"master\"
+}
+"
+
+json=$(jq -n \
+--arg title "${INPUT_LIBRARY_NAME} ${VERSION}" \
+--arg incoming_repo_and_branch "${REPO_OWNER}:${branch_name}" \
+"${jsontemplate}")
+
+
+echo -e "\e[34mCurling...\e[0m"
+result=$(curl -X POST \
+  https://api.github.com/repos/ponylang/main.actor-package-markdown/pulls \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -u "${RELEASE_TOKEN}" \
+  --data "${json}")
+
+rslt_scan=$(echo "${result}" | jq -r '.id')
+if [ "$rslt_scan" != null ]; then
+  echo "\e[34mPR successfully created!\e[0m"
+else
+  echo "\e[31mUnable to create PR, here's the curl output..."
+  echo "${result}\e[0m"
+  exit 1
+fi