Merge branch 'develop' for 1.3.0

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing and Maintaining
+
+First, thank you for taking the time to contribute!
+
+The following is a set of guidelines for contributors as well as information and instructions around our maintenance process. The two are closely tied together in terms of how we all work together and set expectations, so while you may not need to know everything in here to submit an issue or pull request, it's best to keep them in the same document.
+
+## Ways to contribute
+
+Contributing isn't just writing code - it's anything that improves the project. All contributions for our GitHub Actions for WordPress are managed right here on GitHub. Here are some ways you can help:
+
+### Reporting bugs
+
+If you're running into an issue with the action, please take a look through [existing issues](https://github.com/10up/action-wordpress-plugin-deploy/issues) and [open a new one](https://github.com/10up/action-wordpress-plugin-deploy/issues/new) if needed. If you're able, include a link to the log output from the failed run.
+
+### Suggesting enhancements
+
+New features and enhancements are also managed via [issues](https://github.com/10up/action-wordpress-plugin-deploy/issues).
+
+### Pull requests
+
+Pull requests represent a proposed solution to a specified problem. They should always reference an issue that describes the problem and contains discussion about the problem itself. Discussion on pull requests should be limited to the pull request itself, i.e. code review.
+
+For more on how 10up writes and manages code, check out our [10up Engineering Best Practices](https://10up.github.io/Engineering-Best-Practices/).
+
+## Workflow
+
+This repository currently uses the `develop` branch to reflect active work and `master` to represent the latest tagged release. Both should typically be usable and frequently the same, but we request that pull requests be opened against `develop` and usage of the action be against `master` or a specific tag. New releases will be tagged as updates are made.
+
+## Release instructions
+
+1. [Create a new release](https://github.com/10up/action-wordpress-plugin-deploy/releases/new)
+2. Ensure it appears in the GitHub Marketplace correctly
+3. Celebrate shipping!

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Helen Hou-Sandi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,48 +1,83 @@
 # WordPress.org Plugin Deploy
 
-This Action commits the contents of your Git tag to the WordPress.org plugin repository using the same tag name. It excludes files in `.git` and `.github` subdirectories and moves anything from a `.wordpress-org` subdirectory to the top-level `assets` directory in Subversion (plugin banners, icons, and screenshots).
+This Action commits the contents of your Git tag to the WordPress.org plugin repository using the same tag name. It can exclude files as defined in either `.distignore` or `.gitattributes`, and moves anything from a `.wordpress-org` subdirectory to the top-level `assets` directory in Subversion (plugin banners, icons, and screenshots).
+
+### ☞ For updating the readme and items in the assets directory between releases, please see our [WordPress.org Plugin Readme/Assets Update Action](https://github.com/10up/action-wordpress-plugin-asset-update)
 
 ## Configuration
 
 ### Required secrets
 * `SVN_USERNAME`
 * `SVN_PASSWORD`
-* `GITHUB_TOKEN` - you do not need to generate one but you do have to explicitly make it available to the Action
 
-Secrets can be set while editing your workflow or in the repository settings. They cannot be viewed once stored. [GitHub secrets documentation](https://developer.github.com/actions/creating-workflows/storing-secrets/)
+[Secrets are set in your repository settings](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables). They cannot be viewed once stored.
 
 ### Optional environment variables
-* `SLUG` - defaults to the respository name, customizable in case your WordPress repository has a different slug. This should be a very rare case as WordPress assumes that the directory and initial plugin file have the same slug.
-* `VERSION` - defaults to the tag name; do not recommend setting this except for testing purposes
-* `ASSETS_DIR` - defaults to `.wordpress-org`, customizable for other locations of WordPress.org plugin repository-specific assets that belong in the top-level `assets` directory (the one on the same level as `trunk`)
+* `SLUG` - defaults to the repository name, customizable in case your WordPress repository has a different slug or is capitalized differently.
+* `VERSION` - defaults to the tag name; do not recommend setting this except for testing purposes.
+* `ASSETS_DIR` - defaults to `.wordpress-org`, customizable for other locations of WordPress.org plugin repository-specific assets that belong in the top-level `assets` directory (the one on the same level as `trunk`).
 
-### Known issues
-* Currently the `tags` filter on the `push` action does not seem to work correctly, so we target the `refs/tags/*` naming of a branch instead. Ideally for readability and correctness this would use something like `tags: - *`.
+## Excluding files from deployment
+If there are files or directories to be excluded from deployment, such as tests or editor config files, they can be specified in either a `.distignore` file or a `.gitattributes` file using the `export-ignore` directive. If a `.distignore` file is present, it will be used; if not, the Action will look for a `.gitattributes` file and barring that, will write a basic temporary `.gitattributes` into place before proceeding so that no Git/GitHub-specific files are included.
 
-## Example Workflow File
+`.distignore` is useful particularly when there are built files that are in `.gitignore`, and is a file that is used in [WP-CLI](https://wp-cli.org/). For modern plugin setups with a build step and no built files committed to the repository, this is the way forward. `.gitattributes` is useful for plugins that don't run a build step as a part of the Actions workflow and also allows for GitHub's generated ZIP files to contain the same contents as what is committed to WordPress.org. If you would like to attach a ZIP file with the proper contents that decompresses to a folder name without version number as WordPress generally expects, you can add steps to your workflow that generate the ZIP and attach it to the GitHub release (concrete examples to come).
+
+### Sample baseline files
+
+#### `.distignore`
+
+**Notes:** `.distignore` is for files to be ignored **only**; it does not currently allow negation like `.gitignore`. This comes from its current expected syntax in WP-CLI's [`wp dist-archive` command](https://github.com/wp-cli/dist-archive-command/). It is possible that this Action will allow for includes via something like a `.distinclude` file in the future, or that WP-CLI itself makes a change that this Action will reflect for consistency. It also will need to contain more than `.gitattributes` because that method **also** respects `.gitignore`.
+
+```
+/.wordpress-org
+/.git
+/.github
+/node_modules
+
+.distignore
+.gitignore
 ```
+
+#### `.gitattributes`
+
+```gitattributes
+# Directories
+/.wordpress-org export-ignore
+/.github export-ignore
+
+# Files
+/.gitattributes export-ignore
+/.gitignore export-ignore
+```
+
+
+## Example Workflow File
+```yml
 name: Deploy to WordPress.org
 on:
   push:
-    branches:
-    - refs/tags/*
+    tags:
+    - "*"
 jobs:
   tag:
     name: New tag
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@master
+    - name: Build
+      run: |
+        npm install
+        npm run build
     - name: WordPress Plugin Deploy
       uses: 10up/action-wordpress-plugin-deploy@master
       env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         SVN_PASSWORD: ${{ secrets.SVN_PASSWORD }}
         SVN_USERNAME: ${{ secrets.SVN_USERNAME }}
         SLUG: my-super-cool-plugin
 ```
 
 ## Contributing
-Want to help? Check out our [contributing guidelines](../CONTRIBUTING.md) to get started.
+Want to help? Check out our [contributing guidelines](CONTRIBUTING.md) to get started.
 
 <p align="center">
 <a href="http://10up.com/contact/"><img src="https://10updotcom-wpengine.s3.amazonaws.com/uploads/2016/10/10up-Github-Banner.png" width="850"></a>
@@ -52,3 +87,4 @@ Want to help? Check out our [contributing guidelines](../CONTRIBUTING.md) to get
 
 Our GitHub Actions are available for use and remix under the MIT license.
 
+### ☞ Check out our [collection of WordPress-focused GitHub Actions](https://github.com/10up/actions-wordpress)

entrypoint.sh

@@ -20,11 +20,6 @@ if [[ -z "$SVN_PASSWORD" ]]; then
 	exit 1
 fi
 
-if [[ -z "$GITHUB_TOKEN" ]]; then
-	echo "Set the GITHUB_TOKEN env variable"
-	exit 1
-fi
-
 # Allow some ENV variables to be customized
 if [[ -z "$SLUG" ]]; then
 	SLUG=${GITHUB_REPOSITORY#*/}
@@ -54,39 +49,48 @@ svn update --set-depth infinity assets
 svn update --set-depth infinity trunk
 
 echo "➤ Copying files..."
-cd "$GITHUB_WORKSPACE"
-
-# "Export" a cleaned copy to a temp directory
-TMP_DIR="/github/archivetmp"
-mkdir "$TMP_DIR"
-
-git config --global user.email "[email protected]"
-git config --global user.name "10upbot on GitHub"
-
-# If there's no .gitattributes file, write a default one into place
-if [[ ! -e "$GITHUB_WORKSPACE/.gitattributes" ]]; then
-	cat > "$GITHUB_WORKSPACE/.gitattributes" <<-EOL
-	/$ASSETS_DIR export-ignore
-	/.gitattributes export-ignore
-	/.gitignore export-ignore
-	/.github export-ignore
-	EOL
-
-	# Ensure we are in the $GITHUB_WORKSPACE directory, just in case
-	# The .gitattributes file has to be committed to be used
-	# Just don't push it to the origin repo :)
-	git add .gitattributes && git commit -m "Add .gitattributes file"
+if [[ -e "$GITHUB_WORKSPACE/.distignore" ]]; then
+	echo "ℹ︎ Using .distignore"
+	# Copy from current branch to /trunk, excluding dotorg assets
+	# The --delete flag will delete anything in destination that no longer exists in source
+	rsync -rc --exclude-from="$GITHUB_WORKSPACE/.distignore" "$GITHUB_WORKSPACE/" trunk/ --delete
+else
+	echo "ℹ︎ Using .gitattributes"
+
+	cd "$GITHUB_WORKSPACE"
+
+	# "Export" a cleaned copy to a temp directory
+	TMP_DIR="/github/archivetmp"
+	mkdir "$TMP_DIR"
+
+	git config --global user.email "[email protected]"
+	git config --global user.name "10upbot on GitHub"
+
+	# If there's no .gitattributes file, write a default one into place
+	if [[ ! -e "$GITHUB_WORKSPACE/.gitattributes" ]]; then
+		cat > "$GITHUB_WORKSPACE/.gitattributes" <<-EOL
+		/$ASSETS_DIR export-ignore
+		/.gitattributes export-ignore
+		/.gitignore export-ignore
+		/.github export-ignore
+		EOL
+
+		# Ensure we are in the $GITHUB_WORKSPACE directory, just in case
+		# The .gitattributes file has to be committed to be used
+		# Just don't push it to the origin repo :)
+		git add .gitattributes && git commit -m "Add .gitattributes file"
+	fi
+
+	# This will exclude everything in the .gitattributes file with the export-ignore flag
+	git archive HEAD | tar x --directory="$TMP_DIR"
+
+	cd "$SVN_DIR"
+
+	# Copy from clean copy to /trunk, excluding dotorg assets
+	# The --delete flag will delete anything in destination that no longer exists in source
+	rsync -rc "$TMP_DIR/" trunk/ --delete
 fi
 
-# This will exclude everything in the .gitattributes file with the export-ignore flag
-git archive HEAD | tar x --directory="$TMP_DIR"
-
-cd "$SVN_DIR"
-
-# Copy from clean copy to /trunk, excluding dotorg assets
-# The --delete flag will delete anything in destination that no longer exists in source
-rsync -rc "$TMP_DIR/" trunk/ --delete
-
 # Copy dotorg assets to /assets
 rsync -rc "$GITHUB_WORKSPACE/$ASSETS_DIR/" assets/ --delete