material-motion/tools

The Material Motion team's tools

Material Motion Tools

Welcome to the Material Motion's tools documentation.

Installation

Our team uses a custom tool called mdm to manage our team's tooling. We encourage adding this tool to your PATH so that you can access it from anywhere on your computer:

git clone --recursive [email protected]:material-motion/tools.git
cd tools
echo "export PATH=$(dirname $(find $(pwd) -regex '.*bin/mdm')):\$PATH"

Add the output path to whichever file your shell uses to configure environment variables. This is often ~/.bash_profile or ~/.bashrc.

# edit ~/.bash_profile
source ~/.bash_profile

You can now run the mdm tool installer like so:

mdm tools

Or the automated variant:

mdm tools install

Learn more about each mdm command by running mdm help or by reading the docs on GitHub.

License

This work is licensed under a Creative Commons Attribution 4.0 International License.

tools's Issues

Define our release process for web

Content goes here: https://material-motion.gitbooks.io/material-motion-team/content/release_process/web.html

arc diff post-diff should update relevant issue

In arc's post-diff phase we should check the diff message for a reference to a GitHub issue. If an issue is referenced as being "closed", we should update the corresponding issue's labels to "flow: In review".

Research required here:

• Identify how to extend the arc post-diff phase.

Dashboard

Create a dashboard for all of our work.

This work will require a server that is capable of collecting, storing, and serving statistics.

Some stats we should keep track of:

• Number of stars, forks, watchers, and issues over time per repo.
• Number of repos over time.
• Number of contributors over time per repo.
• Number of active contributors over time (one commit/week) per repo.
• Number of team members over time.
• Nmber of diffs sent out over time.
• Number of landed diffs over time.
• Average "in review" time for a diff.
• Average "time-to-initial-response" for a new github issue.
• Event: Release cut per repo.
• Event: Blog post.

For things being tracked over time, a one hour window of granularity would be nice to have.

Bucket features:

• By platform.

Filter features:

• By platform.
• By repo.

DB schema:

• LOGS: key, type, value, timestamp

e.g. Stats: github.com/material-motion-runtime, stars, 5, [timestamp]
e.g. Event: [null], blog_post, [url], [timestamp]

When should we give write access to casual contributors?

Background: https://github.com/Moya/contributors

The idea here is to give write access to the main repo early and often. Giving write access allows the community to triage issues, work on features in the same repo, and generally get higher visibility.

The key is that we'll still have a core contributor pool with admin rights. Only the core + frequent contributor pools will have push rights to develop, and only the core team to stable.

Let's start a discussion here and see how we feel about this idea.

mdm publish phabricator

mdm publish phabricator

Creates a Diffusion repo for the current git repo if one doesn't already exist.

`mdm dir runtime` should resolve to a platform if possible

From @pingpongboss:

Also, since it's relatively rare for any of us to have more than 2 platform repos, maybe also infer -platform.

So mdm dir runtime returns material-motion-runtime-android for me.

Define our release process for iOS

Content goes here: https://material-motion.gitbooks.io/material-motion-team/content/release_process/appleos.html

• Generating api diffs for the changelog.
• Generating change summation for the changelog.
• Generating API documentation.
• Pushing API documentation to a website.

.arcconfig cares what your local remote is called

For .arcconfig to work, it needs to know the name of your remote, which means we are dictating as a team that everyone's material-motion remote needs to be called origin. I typically point origin at my personal fork, to avoid accidentally pushing things to shared history before they are final.

Since we're using Phabricator diffs instead of personal forks for code review, and since we aren't calling any branches master, this is a low priority change (it's probably OK to call your remote origin). Still, ideally we wouldn't care how people configured their workstations.

Use "needs" for "Needing research" and "Needing clarification" labels

Need to update the labels.json map and actually implement label renaming in the mdm gh labels feature.

Simple milestone interface

This is a call for a super-simple org-wide milestone viewer.

A v1 of this tool would simply list every milestone in the org, sorted by date. Each milestone has a link to the github UI.

A v2 of this would show % completion of the milestones.

Extra features:

• List which issues are currently "blocked".

Run sudo npm install in third_party/gh during mdm tools install

mdm repo commands

mdm repo create

• Create a new GitHub repository.
• Clone the repo locally.
• Run yo mm-github.
• Set up develop/stable branches.
• Push initial commit.

Dead links: table of contents: starmap contributor essentials: Writing Prose & GitBook

Move mdm to its own repo

The toolchain for mdm is now sufficiently developed to justify graduating it to its own repo.

What needs to be moved:

• The mdm toolchain.
• Our yeoman generators.

Change discord instant invite to link to the #welcome channel

It presently invites people to the #general channel.

Links need to be fixed in the team docs:

• https://material-motion.gitbooks.io/material-motion-team/content/
• https://material-motion.gitbooks.io/material-motion-team/content/community/communication.html

Linter to enforce TODOs have GitHub issues

We should have a linter that looks for TODO comments and ensures they have a valid GitHub issue, e.g.

// TODO(https://github.com/material-motion/project-name/issues/18): 
// Describe TODO here

Dead link: Issues: Milestones: Release process

Dead link: Starmap contributing: patch process: governence

Define our release process for Android

Content goes here: https://material-motion.gitbooks.io/material-motion-team/content/release_process/android.html

• Gradle should auto-publish the documentation.

Build a dashboard showing our yearly commits as a team

https://developer.github.com/v3/repos/statistics/#get-the-number-of-additions-and-deletions-per-week

Could build some cool visualizations with that.

mdm browse <repo name>

mdm browse <repo name>

Opens a web browser to the repo with the given name.

Examples:

mdm browse team
mdm browse runtime-objc

When should tools go in their own repo vs here?

Opening up a discussion for us to discuss thoughts here.

Should we treat the team repo as a monorepo for all of our tools? Should we break things out in to their own repos?

Should we pull mdm out to its own repo so that our tools live separate from the team docs?

Cannot find babel-polyfill

When running an mdm command, I get Cannot find babel-polyfill:

$ mdm publish github material-motion material-motion-experiments-js
About to create a new GitHub repository.
Please confirm the details below:

    URL: https://github.com/material-motion/material-motion-experiments-js
    Command: mdm gh repo -u material-motion --new material-motion-experiments-js

Press enter to continue...
module.js:442
    throw err;
    ^

Error: Cannot find module 'babel-polyfill'
    at Function.Module._resolveFilename (module.js:440:15)
    at Function.Module._load (module.js:388:25)
    at Module.require (module.js:468:17)
    at require (internal/module.js:20:19)
    at Object.<anonymous> (~/Projects/material-motion-team/third_party/gh/lib/cmd.js:14:1)
    at Module._compile (module.js:541:32)
    at Object.Module._extensions..js (module.js:550:10)
    at Module.load (module.js:458:32)
    at tryModuleLoad (module.js:417:12)
    at Function.Module._load (module.js:409:3)
~/Projects/material-motion-team/contributor_tools/publish/publish: line 57: [: ==: unary operator expected
module.js:442
    throw err;
    ^

Error: Cannot find module 'babel-polyfill'
    at Function.Module._resolveFilename (module.js:440:15)
    at Function.Module._load (module.js:388:25)
    at Module.require (module.js:468:17)
    at require (internal/module.js:20:19)
    at Object.<anonymous> (~/Projects/material-motion-team/third_party/gh/lib/cmd.js:14:1)
    at Module._compile (module.js:541:32)
    at Object.Module._extensions..js (module.js:550:10)
    at Module.load (module.js:458:32)
    at tryModuleLoad (module.js:417:12)
    at Function.Module._load (module.js:409:3)

material-motion detection doesn't seem to work

material-motion-experiments-js $ mdm publish github
No material-motion prefix detected. Please provide an owner.

Use HTTPS for codereview.cc

mdm gh

Rather than take over the global gh command, we should allow our fork to be invoked via the mdm harness.

mdm release merge should check out `develop` upon completion

It currently ends the operation with stable checked out.

Make all tools installers output version numbers

Use nodejs installer as a template for output.

`mdm new repo` android version and `mdm publish github` both wants user supplied %owner% and %repo name%

Figure out how to share this.

Spec out what the Github issue labels mean

mdm dir <repo>

mdm dir [repo]

Output the directory for the given repo, if it exists on disk.

This tool will use a convention-oriented approach to finding repos. It will use the following heuristics:

• If [repo] has material-motion- prefix, remove it.
• Check existence of folder named [repo] or material-motion-[repo] adjacent to mdm's git repository.
• If either exists, output the complete path.

Standardize our GitHub issue labels

Need the following:

• is: Blocking next release
• is: Needing clarification
• is: Needing research
• is: Working as intended
• status: Blocked
• status: Ready for action
• status: In progress
• status: In review
• type: API change
• type: Bug
• type: Documentation
• type: Feature request
• type: Internal cleanup
• type: Newbie friendly
• type: Process
• type: Question
• type: Visual bug
• type: Won't fix

Fold `mdm edit` and `mdm new command`

Both can live under mdm edit, an unrecognized command can be implied as a new command, with a prompt.

In general, try to group the mdm subcommands in a way that makes sense. For instance, mdm new repo and mdm new command don't really belong together in the same subcommand.

Onboarding for "regular contributors" and "casual contributors"

Regular contributors (including core contributors) will be expected to use the same tools as the rest of the team.

Optimize casual contributor onboarding for pull requests and making changes fast/easy.

Open source

This thread outlines the steps we'll take to flip our open source bits.

Verify for every GitHub repo:

• issues are turned on
• wiki is turned off
• squash and merge is the default operation.
• There is a develop branch, and it is the default.
• There is no master branch.
• Enable branch protection on develop.
  • Enable "Protect this branch"
  • Enable "Restrict who can push to this branch"
  • Add the relevant "regular contributors" team for that platform.
  • Add the core team.
• Enable branch protection on stable, if it's available.
  • Enable "Protect this branch"
  • Enable "Restrict who can push to this branch"
  • Add the core team.
• LICENSE exists and is Apache 2.0
• CONTRIBUTING.md exists
• AUTHORS exists
• Delete any CONTRIBUTORS file
• README.md exists and includes license blurb.

## License

Licensed under the Apache 2.0 license. See LICENSE for details.

• Verify that every source file has the correct header.
• material-motion/material-motion-starmap
• material-motion/material-motion-experiments-js
• material-motion/material-motion-experiments-swift
• material-motion/material-motion-experiments-objc
• material-motion/material-motion-experiments-android
• material-motion/material-motion-conventions-android
• material-motion/material-motion-team
• material-motion/material-motion-hubot
• material-motion/material-motion-expression-android
• material-motion/material-motion-family-tween-android
• material-motion/material-motion-direct-web
• material-motion/material-motion-runtime-objc
• material-motion/material-motion-runtime-android
• material-motion/material-motion-transitions-objc
• material-motion/cocoapods-catalog-by-convention
• material-motion/gh
• Ensure that all of our repos are being mapped in codereview.cc.
• Declare comment bankruptcy for starmap
• Declare comment bankruptcy for team docs
• Flip the public bits on Discord.
• Flip the public bits on GitBook Starmap and team docs.
• Flip the public bits on all GitHub repos.
• Flip the public bits for codereview.cc.
• appsforartists' handle is public to public
• featherless' handle is public to public
• markwei's handle is public to public
• willlarche's handle is public to public

mdm lsc - large-scale changes

mdm lsc <path script>

For large-scale changes.
Runs the script in every github repository in the material-motion organization.

Use cases:

• Changing org-wide content. E.g. adding linters, arc features (e.g. hooks).
• Regenerate documentation.

The command should clone the repositories in a separate directory so that the lsc can easily be managed independently of other changes.

Example lsc for adding a new git submodule:

git checkout -b develop origin/develop
git submodule add <url> third_party/<name>
git commit -am "Add fancy new linter"
git push origin develop

Commands in a script should run without any prompting.

LSCs should be checked in to the team repo alongside the lsc command. Over time this will become a helpful reference.

What's our three-letter-prefix for Objective-C libraries?

Potential options:

• MMO for Material Motion
• MAT for Material
• MOT for Motion

Add .gitignore to our yeoman generators

Each platform/language has its own .gitignore.

Add the file to the relevant directory here: https://github.com/material-motion/material-motion-team/tree/develop/generators/generator-mm-github/app/templates

mdm autocomplete

https://debian-administration.org/article/316/An_introduction_to_bash_completion_part_1

mdm new command <command>

mdm new command <command>

Creates scaffolding for a new command.

Does the following:

1. Creates a new directory named adjacent to the mdm directory.
2. touch <command>/<command>; chmod +x <command>/<command>
3. touch <command>/README.md

mdm new repo <repo>

mdm new repo <repo>

Create a new git repository on local disk.

mdm tools version

mdm tools version should list the version number for each of our tools.

mdm help --all

mdm help --all

Outputs help for every command.

mdm release

Four actions: cut, test, merge, and publish.

Cut creates a release-candidate branch from develop. Sends an email to announce list?

Test runs clean tests on the release candidate or stable branch.

Merge merges the release candidate in to stable.

Publish pushes stable to github, creates the release tag on github.

mdm publish github

mdm publish github

Publishes the current git repository to GitHub.

Must be run from a git repository.

If the git repository has a material-motion prefix, publish without question.
Otherwise, prompt to confirm which org the repo should be placed under (likely material-foundation).

Create a GitHub repository using the gh command line tool.

mdm gh repo --new

Add eslint to arc for JS projects

Here's the current eslintrc: https://github.com/material-motion/material-motion-experiments-js/blob/develop/.eslintrc

There's no parser for eslint yet, so you have to use the regex parser. Pretty easy to find on Google Search.

I'd like to fold our eslint configs into the official Google one at some point: google/eslint-config-google#18

list

Move tooling to it's own repo in material foundation

This will allow easier testing, iteration and improvement from everyone.

mdm release cut should fail if develop != origin/develop

mdm release cut cuts at origin/develop, so if develop != origin/develop then some commits may get missed.

Add team doc on "how do we make new arc linters"