generated from mattermost/mattermost-plugin-starter-template
-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
8 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,73 +1,13 @@ | ||
# Plugin Starter Template ![CircleCI branch](https://img.shields.io/circleci/project/github/mattermost/mattermost-plugin-starter-template/master.svg) | ||
# Doc Up | ||
|
||
This plugin serves as a starting point for writing a Mattermost plugin. Feel free to base your own plugin off this repository. | ||
This plugin makes it easy to mark messages in Mattermost for documentation. Known as doc'ing up. It is meant to work with documentation that lives in GitHub. | ||
|
||
To learn more about plugins, see [our plugin documentation](https://developers.mattermost.com/extend/plugins/). | ||
The plugin is in alpha. | ||
|
||
## Getting Started | ||
Use GitHub's template feature to make a copy of this repository by clicking the "Use this template" button then clone outside of `$GOPATH`. | ||
## FAQ | ||
|
||
Alternatively shallow clone the repository to a directory outside of `$GOPATH` matching your plugin name: | ||
``` | ||
git clone --depth 1 https://github.com/mattermost/mattermost-plugin-starter-template com.example.my-plugin | ||
``` | ||
#### What does this do? | ||
Marking something for documentation, otherwise known as doc'ing up, will create a GitHub issue in the corresponding repository for the documentation type that is selected. This GitHub issue can then be picked up by someone to edit and submit a pull request to update our official documentation. | ||
|
||
Note that this project uses [Go modules](https://github.com/golang/go/wiki/Modules). Be sure to locate the project outside of `$GOPATH`, or allow the use of Go modules within your `$GOPATH` with an `export GO111MODULE=on`. | ||
|
||
Edit `plugin.json` with your `id`, `name`, and `description`: | ||
``` | ||
{ | ||
"id": "com.example.my-plugin", | ||
"name": "My Plugin", | ||
"description": "A plugin to enhance Mattermost." | ||
} | ||
``` | ||
|
||
Build your plugin: | ||
``` | ||
make | ||
``` | ||
|
||
This will produce a single plugin file (with support for multiple architectures) for upload to your Mattermost server: | ||
|
||
``` | ||
dist/com.example.my-plugin.tar.gz | ||
``` | ||
|
||
There is a build target to automate deploying and enabling the plugin to your server, but it requires configuration and [http](https://httpie.org/) to be installed: | ||
``` | ||
export MM_SERVICESETTINGS_SITEURL=http://localhost:8065 | ||
export MM_ADMIN_USERNAME=admin | ||
export MM_ADMIN_PASSWORD=password | ||
make deploy | ||
``` | ||
|
||
Alternatively, if you are running your `mattermost-server` out of a sibling directory by the same name, use the `deploy` target alone to unpack the files into the right directory. You will need to restart your server and manually enable your plugin. | ||
|
||
In production, deploy and upload your plugin via the [System Console](https://about.mattermost.com/default-plugin-uploads). | ||
|
||
## Q&A | ||
|
||
### How do I make a server-only or web app-only plugin? | ||
|
||
Simply delete the `server` or `webapp` folders and remove the corresponding sections from `plugin.json`. The build scripts will skip the missing portions automatically. | ||
|
||
### How do I include assets in the plugin bundle? | ||
|
||
Place them into the `assets` directory. To use an asset at runtime, build the path to your asset and open as a regular file: | ||
|
||
```go | ||
bundlePath, err := p.API.GetBundlePath() | ||
if err != nil { | ||
return errors.Wrap(err, "failed to get bundle path") | ||
} | ||
|
||
profileImage, err := ioutil.ReadFile(filepath.Join(bundlePath, "assets", "profile_image.png")) | ||
if err != nil { | ||
return errors.Wrap(err, "failed to read profile image") | ||
} | ||
|
||
if appErr := p.API.SetProfileImage(userID, profileImage); appErr != nil { | ||
return errors.Wrap(err, "failed to set profile image") | ||
} | ||
``` | ||
#### Why create an issue instead of directly creating a pull request? | ||
Creating a pull request requires intricate knowledge of our documentation repositories, making it difficult for someone not familiar to know exactly where to place the documentation. Creating an issue gives our writers and editors a list of items needing documenation while at the same time making a raw form of the documentation, in the GitHub issue, immediately searchable on the web. |