mattermost-developer-documentation
mattermost-developer-documentation copied to clipboard
mattermost
Expand app quick start guides
Fixes:
- https://mattermost.atlassian.net/browse/MM-39146
- https://mattermost.atlassian.net/browse/MM-36715
- https://mattermost.atlassian.net/browse/MM-37115
- https://github.com/mattermost/mattermost-developer-documentation/issues/942
- https://github.com/mattermost/mattermost-developer-documentation/issues/1028
- https://github.com/mattermost/mattermost-developer-documentation/issues/937
Adds:
- Developer setup guide using new https://github.com/mattermost/mattermost-app-examples repository
- New Python quick start guide for the app framework based on https://github.com/mattermost/mattermost-plugin-apps/pull/352
- Refreshed TypeScript Hello World guide
- Refreshed Go Hello World guide
- Refreshed Go Serverless guide
- New Golang JWT guide
Blocked guides:
- Golang
- Lifecycle - Go error when trying to install and use lifecycle bindings.
- Oauth2 - Requires the entire dev setup to be exposed to the web via something like
ngrok, will require more thought. - Webhooks -
/hello-webhooks infoendpoint does nothing when sent to, app does not report messages to channel.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
Newest code from azigler has been published to preview environment for Git SHA 80371bac8caf5e17f4b26096fee7c022a37a9316
Newest code from mattermod has been published to preview environment for Git SHA 01ff486a1977d7d7352e01af572c8ed3afa4e311
Newest code from azigler has been published to preview environment for Git SHA 1c606765e33547258bd3b93a8bedb46630e2e122
Newest code from azigler has been published to preview environment for Git SHA f18c650e134d4627b413dafe31eb2cb7c3361a92
Newest code from azigler has been published to preview environment for Git SHA cd313c0a4fa01628772a5c2ab0fe0f2d1e85f37c
Newest code from azigler has been published to preview environment for Git SHA 23c76aa36728014cbb4a92207fca4a1f5ab56040
Easy links to view the new pages:
- Developer setup
- Hello World in Go
- Hello World in Python
- JWT in Go
- Serverless on AWS or OpenFaaS in Go
- Hello World in TypeScript
And if you haven't checked it out yet, here's the shiny new repo that houses all these examples, their docker-compose.ymls, and the new dev server docker-compose.yml that makes it super easy to spin up the demos: https://github.com/mattermost/mattermost-app-examples
@levb @mickmister I'd appreciate your technical review on these guides, to make sure I didn't botch anything. You'll see I added a new guide for Python, too.
@mickmister Just a heads up that I noticed some issues with the lifecycle example (I got an error when trying to install and use lifecycle bindings with that example) and the webhooks example (/hello-webhooks info endpoint does nothing when sent to, app does not report messages to channel). If you can help me figure out/unblock those issues and we can get them working again, I can add guides for them in a future PR. The OAuth2 example requires the entire dev setup to be exposed to the web via something like ngrok, so it will require more thought for a future guide.
@cwarnermm @BenLloydPearson I tagged y'all as reviewers on this, if you don't mind taking a look based on the many conversations we've had about these guides. Carrie, can you stick the appropriate review tags on this PR? 🙂 Also, I noticed the TypeScript guide's URL is "js" which isn't a big deal, but any chance we could change it to "ts" and have "js" forward to it? It would be nice for the URL to match the language. Also, if you can figure out how to weight the guides so the three Hello Worlds are first, followed by serverless, followed by JWT, that would be amazing! Then we can re-order the index table on the developer guide, too.
Newest code from cwarnermm has been published to preview environment for Git SHA 23c76aa36728014cbb4a92207fca4a1f5ab56040
Newest code from cwarnermm has been published to preview environment for Git SHA 23c76aa36728014cbb4a92207fca4a1f5ab56040
Newest code from azigler has been published to preview environment for Git SHA 4d18e35f3fd67251344a03c2c77d8b45d3b58123
Newest code from azigler has been published to preview environment for Git SHA e7c9ddd8dffe9c6eea851c2a92ce085b71beca55
Newest code from azigler has been published to preview environment for Git SHA 1014358c916585901b73ebb353e98c22a85af3aa
I missed one. There's a typo in the heading of the /integrate/apps/quickstart/quick-start-js page. It says Create a wello world Mattermost App in TypeScript instead of Create a hello world Mattermost App in TypeScript.
Regarding page weights: the weight of a page determines its order in the LHS. If a weight is not defined then the page is sorted alphabetically. A lower weight value means a higher position in the LHS.
Note that if a directory contains an _index.md file, the weight defined in that file applies to the topic in the parent directory. Weights in other .md files in the same directory are used as normal and the pages are treated as sub-topics of the parent.
Regarding renaming a directory: it's perfectly fine to rename a directory, however page redirects need to be managed. Page redirects are defined in the aliases key of the page frontmatter, the YAML section at the top of each .md file. Each element of the aliases list is transformed to a physical HTML file that contains a redirect to the page you're modifying.
For example, if we wanted to rename the directory /integrate/apps/quickstart/quick-start-js to /integrate/apps/quickstart/quick-start-ts, we would:
- Add an element to the
aliaseslist in the page frontmatter with the current (undesired) path:
---
# ...
aliases:
- /integrate/apps/quickstart/quick-start-js
# ...
---
- Rename the directory from
quick-start-jstoquick-start-ts
I hope this helps! :smile:
docker-compose is not a plugin in the Docker installations I've used over the years; it's a separate program altogether. I also wasn't aware that Docker made this change; they didn't email me about it and I'm subscribed to their mailing list.
Are we suggesting that the reader has "Docker Desktop" installed rather than straight Docker? The Docker that I install on Ubuntu using apt doesn't seem to be "Docker Desktop". We should be explicit about what release of Docker should be used by adding a note section here. There are many developers who will not have known about the changes to docker-compose and will hit errors when trying to run the commands we're documenting.
"Docker Desktop" or "Docker Engine" both work, if they follow the install instructions for whichever one they pick. I will clarify in the instructions.
If you do docker compose version and docker-compose version you'll get the same version, because it's aliased. If docker compose doesn't work for you, then something is wrong with your configuration and I recommend following the installation steps again. As for the docker -v output, on my remote Linux with Docker Engine (the CLI), it's Docker version 20.10.17, build 100c701. On my Mac with Docker Desktop (the application), it's also Docker version 20.10.17, build 100c701 because they're the same under the hood. If someone installs Docker today (either application type) or updates to a modern install (either application type), they get the version with compose as a built-in alias command. They are planning to have this alias in place indefinitely. docker compose is the new standard way the command is written.
I missed one. There's a typo in the heading of the /integrate/apps/quickstart/quick-start-js page. It says Create a wello world Mattermost App in TypeScript instead of Create a hello world Mattermost App in TypeScript.
Hah, fixed! Thanks.
Newest code from azigler has been published to preview environment for Git SHA 3c2338f09be408cb3f3bed0b271efa567647809a
Newest code from azigler has been published to preview environment for Git SHA dd603478f2698f220cf5ebaa456c54708696cb7b
Awesome work @azigler!! I have lots of comments on here. Some of them apply to multiple pages due to similar content existing on different pages. Overall this is looking great! 🚀 Thanks for your work on this!!
Thanks @mickmister for your review! I incorporated most of your suggestions and left some comments.
Newest code from azigler has been published to preview environment for Git SHA fe0a6183ecca9ebe781588360e8095daf5d72aab
Newest code from azigler has been published to preview environment for Git SHA bdfcae0c76dd1bfa6c609f9a134def8b7437471e
Newest code from azigler has been published to preview environment for Git SHA 3cfc7753766ad00019d3663ea95b4be1391a0fc5
Newest code from azigler has been published to preview environment for Git SHA 7760044812a760e8233dce3bda6ec46e48a1982b
Newest code from azigler has been published to preview environment for Git SHA e5760fe89ba7fdf406391c2e5e65c3816590ed3c
Newest code from cwarnermm has been published to preview environment for Git SHA 1acf0cffc975087143e767972ae3ed8aa517d21f
Newest code from levb has been published to preview environment for Git SHA 18451aacde6b80d5c1d66f8bc73dabb2fe3726ec
@azigler - The dev docs site has seen a lot of changes recently. Given the age of this PR, would you be open to reviewing the changes proposed in this PR against content available in production to confirm whether we want to move ahead with this PR?
