mattermost / mattermost-developer-documentation Goto Github PK

We have a mix of YAML (---) and TOML (+++) in page headers. Let's switch them all to use YAML for consistency's sake.

Should we add an "Edit on GitHub" button/link like we do on docs.mattermost.com, so it's obvious where to go to propose changes?

Humble apologies if this has previously been covered, or if I've missed it, but the documentation for how to handle responding to an Interactive Dialog submission appears to be a bit unclear.

Page: https://docs.mattermost.com/developer/interactive-dialogs.html

The text states:

Finally, once the request is submitted, we recommend the integration to respond with a system message or an ephemeral message confirming the submission.

However it is not clear on how to structure this response. I have made attempts to respond with a payload akin to a standard Slash Command response, as well as that for an Interactive Message response. While it is likely that I have simply configured my code incorrectly, I believe having a hard example of how to respond to a Dialog submission would help users, especially as all other submissions and responses on the above documentation page come with payload examples.

https://developers.mattermost.com/extend/plugins/example-plugins/

It would be helpful to have some steps for making code changes, rebuilding, and redeploying server plugins for testing at the bottom of https://github.com/mattermost/mattermost-developer-documentation/blob/master/site/content/extend/plugins/server/hello-world.md#installing-the-plugin.

What's the most efficient approach? Right now I disable the plugin in the Management Console, then:

<plugin dir> $ make deploy # this directory is parallel to the mattermost-server directory

Then I re-enable the plugin and I see my updates. Is this the most efficient way?

Happy to type up the PR if someone can confirm the steps.

Thanks!

It'd be nice to have an edit link on each page to make it apparent that the pages are open to public contributions and make contributing stupid simple. For example, the "Developer Setup" page would have a link like this: Edit on GitHub or maybe just ✏️

• Pick a subdomain.
• Set up a Travis job or something simple to generate the site and push it to an S3 bucket.
• Put CloudFront in front of that bucket and point our subdomain at it.
• Delete the docs directory from the repo.

it seems that we must use dep ensure before make run to start mattermost server, other way it tell me a package is missing.
actual error:
`cmd/mattermost/main.go:9:2: cannot find package "github.com/mattermost/mattermost-server
/cmd/mattermost/commands" in any of:
/home/wsebai/go/src/mattermost-server/vendor/github.com/mattermost/mattermost-server/cmd/mattermost/commands (vendor tree)
/usr/lib/go/src/github.com/mattermost/mattermost-server/cmd/mattermost/commands (from $GOROOT)
/home/wsebai/go/src/github.com/mattermost/mattermost-server/cmd/mattermost/commands (from $GOPATH)

cmd/mattermost/main.go:15:2: cannot find package "github.com/mattermost/mattermost-server/imports" in any of:
/home/wsebai/go/src/mattermost-server/vendor/github.com/mattermost/mattermost-server/imports (vendor tree)
/usr/lib/go/src/github.com/mattermost/mattermost-server/imports (from $GOROOT)
/home/wsebai/go/src/github.com/mattermost/mattermost-server/imports (from $GOPATH)

cmd/mattermost/main.go:12:2: cannot find package "github.com/mattermost/mattermost-server/model/gitlab" in any of:
/home/wsebai/go/src/mattermost-server/vendor/github.com/mattermost/mattermost-server/model/gitlab (vendor tree)
/usr/lib/go/src/github.com/mattermost/mattermost-server/model/gitlab (from $GOROOT)
/home/wsebai/go/src/github.com/mattermost/mattermost-server/model/gitlab (from $GOPATH)
`

Currently (#61), we have contribution guidelines, which combines the contributor flows for each project.

It might be worthwhile moving some of the information to the specific project sections, so that someone working on Redux tickets have a single flow to follow (instead of reading about other repos in that process)

Summary

The list of example channels for new members to join is outdated.

https://developers.mattermost.com/internal/onboarding/new-staff-guide/

Some noted discrepancies, but not a complete list:

• Private Core Team -> Staff
• Community/Customers -> Does not exist
• Platform Meeting -> Does not exist
• Standup -> misspelled. should be Stand-up
• Confidential Bugs -> in Staff, not Contributors

It would be nice to be able to see the draft pages using a special URL.

Request: Update subheadings so it's possible to link to them.

E.g. on this page: https://developers.mattermost.com/extend/plugins/example-plugins/

It would be nice to directly link to a specific plugin example.

Makes it easier to copy a link to a specific section

The blue background covers part of the footer when viewing developers.mattermost.com on an external monitor. I implemented a quick change to fix this, but was wondering if viewing on mobile should be improved (gap between Extend section and footer) before submitting a PR. Thoughts?
Before

After

Mobile

We have a lot of great information available in the Dev Talks on our YouTube page, but they aren't very discoverable. Add a section to the dev site that includes these videos. Ideally this would be automatically generated by querying the YouTube API, and would include both the embedded video, and any text from the video description.

This issue is also being tracked in JIRA.

Context

When selecting a child tab of a parent tab that only contains single-leveled children, the tab stays open and highlighted. Example: Web App > Developer Apps

Selecting any tab should update the RHS content window and the newly clicked tab should remain highlighted. Also, the parent should not collapse.

However, when selecting a child tab of a parent tab that contains multi-leveled children, clicking the child tab collapses its parent tab. Example: Mobile Apps > Developer Setup > Mobile Apps Workflow

Docs request

Investigate whether this is something configurable via Hugo (the tooling that generates the HTML developer documentation). If it is configurable, submit a dev docs PR that incorporates this configuration.

How you can help

Determine whether this user experience is something we can achieve using the existing dev docs tool chain in place. We don't have the answer to this question yet ourselves, so we're not able to provide much direction on how to get started.

Need some better styling for the documentation pages.

Main needs:

• Better text size
• Mattermost colors
• Anything improving readability

With the new automated cherry picks, the documentation needs an update:

• https://developers.mattermost.com/contribute/getting-started/branching/#cherry-pick-process-developer
• https://developers.mattermost.com/contribute/getting-started/code-review/

Also the label list needs an update.

Error: Unable to locate Config file. Perhaps you need to create a new site.
       Run `hugo help new` for details. (Config File "config" Not Found in "[/Users/chris/repos/mattermost/mattermost-developer-documentation]")

Forget to commit something?

Need a design for how the left-hand sidebar will work.

Need to add a mailing list sign-up form that gets notified about new blog posts. Must have a way to unsubscribe.

Need to re-add categories for blog posts and figure out why they were working locally but not on the production or other Travis built versions of the site.

They were removed in #228

1. Add "Beta" label to sidebar as well
   

2. For the subsection headings, should the title be of the form Web App Plugins: Reference, or is that redundant?

Completely 0/5, just wondering if someone lands on the page, is it obvious what reference they're looking at (until they check the sidebar, which may be more crowded once we add the other sections to the site)

Gonna mull over this for another day or two at least before doing anything. Feedback appreciated.

Step One: Improve Existing Documentation

The existing documentation could be more thorough, and I'd like to add some examples. Examples are a bit weird, because they're expected to be complete, functional, and runnable on the playground. Of course, we can't run plugins on the playground, but I think a decent way to go is to create an exampleplugin package that drives the example. It would provide an exampleplugin.Main function that makes it interchangeable with rpcplugin:

package main

import (
	"fmt"
	"net/http"

        // When building a real plugin, replace "exampleplugin" with "rpcplugin".
	pluginimpl "github.com/mattermost/mattermost-server/plugin/exampleplugin"
)

type MyPlugin struct{}

func (p *MyPlugin) ServeHTTP(w http.ResponseWriter, _ *http.Request) {
	fmt.Fprintf(w, "Hello, world!")
}

func main() {
	pluginimpl.Main(&MyPlugin{})
}

exampleplugin.Main would invoke whatever hooks the plugin has implemented with representative input, then display some feedback in stdout as necessary to make it clear what's happening.

This would hopefully allow users to get a more hands-on idea of what the inputs and outputs of the API look like.

Step Two: Integrate the Documentation into the Site

We can use the godoc package to parse all of the comments in the standard way: https://godoc.org/golang.org/x/tools/godoc

We more or less just need to make a template and wrap that in a nice little command.

The thing I'm not sure about here is the best way to work this into the build process. Should we just generate site/content/extend/server/api-reference.md entirely before invoking the hugo command to generate our HTML? That wouldn't be too bad, but I feel like there's probably a more elegant way to integrate with hugo. (Update: Generating data templates instead of markdown would probably be one step better.)

High level design.

• Getting Started
  • Contribution Guidelines
  • Core Committers
  • Project Repositories
• Server
  • Environment Setup
  • Workflow
  • Systems
    • Application Layer
    • Model and Driver
    • REST API
    • Store Layer
    • CLI
    • WebSocket
    • Job Server
    • Utilities
• Webapp
  • Environment Setup
  • Workflow
  • Systems
    • Router
    • Components
    • Actions
    • Reducers
    • Selectors
    • SASS
• Mobile
  • Environment Setup
  • Workflow
  • Systems
    • TBD
• Redux
  • Environment Setup
  • Workflow
  • Systems
    • Actions
    • Reducers
    • Selectors
• Desktop
  • Environment Setup
  • Workflow
  • Systems
    • TBD

• Go to this page: http://mattermost-developer-documentation.s3-website-us-east-1.amazonaws.com/branches/master/extend/plugins/
• Click the "server" link at the bottom of the page body.

It sends you here (which is wrong): http://mattermost-developer-documentation.s3-website-us-east-1.amazonaws.com/branches/master/extend/plugins/extend/plugins/server/hello-world

For the notification bar that can be enabled by setting params.notifcation.enable to true in config.toml

• Make it closable
• When at top, don't cover menus but float (stay at top of screen) on scroll

I often find myself copying / pasting / URL hacking so I can read over PRs on a built version of the site. Travis could make this nicer.

AKA fix all the bugs related to it being hosted at https://jwilander.github.io/mattermost-developer-documentation

High level design.

• Getting Started
  • How Should I Integrate?
• Incoming Webhooks
  • Usage
  • Example
• Outgoing Webhooks
  • Usage
  • Example
• Slash Commands
  • Usage
  • Example
• Message Attachments
  • Interactive Message Buttons
  • Message Builder - similar to https://api.slack.com/docs/messages/builder
• REST API
  • Usage
  • API Reference - link out to api.mattermost.com
  • Personal Access Tokens
  • Example - probably CH's bot sample
• OAuth 2.0
  • Example - probably EN's oauth sample

Placeholder for the design and styling work for the blog.

Currently it's set up with MailJet, but we might want to switch to MailChimp since all our other email campaigns use that service.

Jason to discuss with marketing team how important this is, or whether we'll use MailJet for the developers site.

For example, see https://developers.mattermost.com/internal/release-process/

Neither "Onboarding" nor "Release Process" should have expand / collapse buttons.

The extend/server/hello-world page has some Go / YAML blocks that need highlighting. I thought Hugo had syntax highlighting built in, but it doesn't seem to just work.

Repro:

1. Go to https://developers.mattermost.com/internal/writing-a-blog-post/
2. Read the doc, and notice that the numbered list restarts at 1 after the code block

This is even though the GitHub .md file has the correct numbered list

https://github.com/mattermost/mattermost-developer-documentation/edit/master/site/content/internal/writing-a-blog-post.md

Contributions without tickets, including raising a proposal for a help wanted issue, are documented here

https://developers.mattermost.com/contribute/getting-started/contributions-without-ticket/

However, core committer process for creating these Help Wanted issues is not documented. Propose we do so. The process is roughly:

1. Create a Jira issue with a clear title and description, including any information that would help a contributor get started.
2. If applicable, have the issue reviewed by a PM or another core committer
3. Add "Help Wanted" fix version, which automatically creates a Help Wanted GitHub issue for that Jira issue. This automation is done via the Zapier tool.
4. Follow up on questions from contributors on the help wanted issue

Note: As of August 6, the Zapier automation is broken due to an issue on Zapier's end. Hence, you will need to create the issue manually on step 3. For an example issue with an intro that helps new contributors to get started can be found here: mattermost/mattermost#11675

• https://developers.mattermost.com/contribute/server/#server-packages lists util as a server package, when it should be utils.
• Broken link for api4 package on https://developers.mattermost.com/contribute/server/developer-workflow/#workflow

Things that people that aren't Mattermost employees are extremely unlikely to care about, such as "how to ssh into a machine", or "how to upgrade go on the build servers".

Should this stuff go into the contribute section? Should it go in another site altogether such as a wiki?

I think there are at least two important factors to consider:

• Keeping noise and UI clutter to a minimum for our visitors: Most visitors won't care and shouldn't have to visually filter this stuff out of a sidebar or navigation UI. You shouldn't really see this section unless you're looking for it.
• Keeping low maintenance overhead for internal documentation: The bar for internal documentation doesn't need to be as high as our public documentation. Things don't need to look pretty, get PM approval, go through dev review, or be dumbed down for the general public. A dumping ground for knowledge is all we need.

High level design. Individual issues can be opened for each section.

• Plugins
  • Overview
  • The Manifest (with reference / documentation parsed from source)
  • Front-end
    • Introduction - How front-end customization is done, broad overview.
    • Quickstart - Hello world!
    • API Reference - Which elements can be plugged into, etc.
    • Playground? - Seems like it would be feasible to create a playground environment for UI elements.
  • Back-end
    • Introduction - How back-end customization is done, broad overview.
    • Quickstart - Hello world!
    • API Reference - More or less the godoc page, reskinned.
  • Examples
• Forking Mattermost

i build my android apk (via make build-android), but i see only spash screen

java.lang.RuntimeException: Unable to load script from assets 'index.android.bundle'. Make sure your bundle is packaged correctly or you're running a packager server.
   at com.facebook.react.bridge.CatalystInstanceImpl.jniLoadScriptFromAssets(Native Method)
   at com.facebook.react.bridge.CatalystInstanceImpl.loadScriptFromAssets(CatalystInstanceImpl.java:216)
   at com.facebook.react.bridge.JSBundleLoader$1.loadScript(JSBundleLoader.java:32)
   at com.facebook.react.bridge.CatalystInstanceImpl.runJSBundle(CatalystInstanceImpl.java:243)
   at com.facebook.react.ReactInstanceManager.createReactContext(ReactInstanceManager.java:1116)
   at com.facebook.react.ReactInstanceManager.access$900(ReactInstanceManager.java:117)
   at com.facebook.react.ReactInstanceManager$5.run(ReactInstanceManager.java:916)
   at java.lang.Thread.run(Thread.java:818)

also
i try make unsigned-android, but i cant install apk

Give an easy way for community to share their integrations.

E.g. having a text like https://docs.mattermost.com/developer/webhooks-incoming.html#share-your-integration, or having a link somewhere in the page footer.

1. What is the note at the top?
2. Should "API" heading size match "Testing"? Feels a little large.

3. Same with heading size of the individual "API" heading sizes. We can probably just match the sizes from Web App Plugins > Reference
   

the current docuementation here is probably written with ubuntu 16.04 in mind which still used upstart. doing the steps on 18.04 won't work since it's using systemd.

the docs need to be updated to reflect those changes since this will also not work on newer rhel releases and 16.04 will be EOL in 2020.

Elias also pointed out that it might be better to make the docs system agnostic and not show include any particular step by step solution for the system files but rather point in the right direction, which would prevent situations like this in the future.

Our build process utilizes hidden environment variables to protect private information like our AWS, GitHub, and YouTube API credentials. As a security precaution, these variables are not available in builds that are triggered by a PR submitted from a fork of the repo. We'll need to modify the build process to avoid executing the steps that require these variables in this case. See #77 for details.

step 6 recommends installing babun which is officially discontinued as of january this year

an alternative should be found somehow. like mingw or cygwin or something like that.

We do have a great style guide for code: https://docs.mattermost.com/developer/style-guide.html
However, we dont seem to have any guidelines for writing content, in other words, a documentation style guide. A documentation style guide is critical to ensure that the format, content, word usage, typographic conventions, and language is consistent across the document.

Right now you need to run hugo in the /site directory which will dump the built site into /docs which is pretty messy and will likely make rebasing a pain.

Propose tweaking the top portion of the manifest reference

Current:

Proposed (up for feedback):

Manifest Reference
===============

The plugin manifest defines the metadata required to load and present your plugin. The manifest file should be named plugin.json or plugin.yaml and placed in the top of your plugin bundle.

Example plugin.yaml:

{code}
id: com.mycompany.myplugin
name: My Plugin
description: This is my plugin. It does stuff.
backend:
    executable: myplugin
settings_schema:
    settings:
        enable_extra_thing:
            type: bool
            display_name: Enable Extra Thing
            help_text: When true, an extra thing will be enabled!
            default: false
{code}

Table of Contents
-------------------

<TOC items here>

Followed by the documentation

It might be worth reviewing the doc formatting as well. It's okay for now, but it's a little hard to follow especially with the indentation towards the end.

Currently, the Developer Setup page reads:

This includes NPM which is also needed. Currently version 10.11.0 is recommended with npm 6.4.1. 11.x is not working.

After several hours of trying to create a reproducible build environment for our needs, I believe that the version 10.11.0 with npm 6.4.1 is not only recommended, it is required.

None of the official current releases of NodeJS build mattermost-mobile successfully.

I could not get any of these versions to work:
10.16.3 (npm 6.9.0) - memory leak around source-map
12.9.1 (npm 6.10.2) - problems with redux and deps
8.16.1 (npm 6.4.1) - can't remember the error(s)

That means that none of the nodejs docker images worked for us. I am not a technical user anymore so I could have missed something.

There is one easy way to prevent people from spending the time I did on this.

Would you be willing to consider making the assertion about nodejs and npm versions more strongly?

Possibly include that information in the mattermost-mobile project readme, update the Developer Setup page to make it clear that this is what Mattermost is using.