https://github.com/microplan-xyz/microplan
Plan your project from command line
https://github.com/microplan-xyz/microplan
github planning project
Last synced: about 21 hours ago
JSON representation
Plan your project from command line
- Host: GitHub
- URL: https://github.com/microplan-xyz/microplan
- Owner: microplan-xyz
- License: mit
- Created: 2016-11-13T12:53:17.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2020-05-22T18:33:19.000Z (about 6 years ago)
- Last Synced: 2025-08-17T00:28:56.945Z (10 months ago)
- Topics: github, planning, project
- Language: JavaScript
- Size: 151 KB
- Stars: 10
- Watchers: 4
- Forks: 7
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
Plan your projects from the command line
[](https://semaphoreci.com/scriptnull/microplan)
[](https://badge.fury.io/js/microplan)
[](https://www.npmjs.com/package/microplan)
[](https://github.com/microplan-xyz/microplan/blob/master/LICENSE)
[](https://gitter.im/microplan-xyz/Lobby)
[](http://makeapullrequest.com)
### Inspiration
> "I am a strong believer that great software comes from great people. If you worry only about the technology side of the equation, you're missing way more than half of the picture"
>
> -- Sam Newman ( "Evolutionary Architect", Building Microservices)
We want to solve the "Planning" side of the equation. And we want our tool to be handy. Talking of handy tools, the terminal comes to mind. So why not use that as our playground?
### Installation
Microplan requires Node.js 0.12 or greater along with npm
```bash
$ npm install -g microplan
```
### Planning Tools
The following issue trackers/messaging tools are supported by microplan.
| Tool | Status |
|------|--------|
| [Github](https://github.com/) | AVAILABLE |
| [Gitlab](https://gitlab.com/) | AVAILABLE |
| [Gitter](https://gitter.im) | AVAILABLE |
### Getting Started
Let's say you want to create a user registration form in your app. Your workflow might look something like this:
- Ping the UX team on Slack/Gitter to ask how the UI should look like
- Open an issue in the front-end repo (on GitHub) to add a page and notify about it (on Gitter)
- Open another issue in the back-end repo (on GitLab ) to add an API endpoint
Wait. This seems all over the place! :O
What if you had a consolidated solution baked right into your terminal?
This is where microplan comes into the picture! Let's get started and publish this plan to the specified tools from the cozy comfort of your command line.
### Login
Use the `login` command to store your credentials in the `.microplan` file in your HOME folder
- Generate your GitHub `token` [here](https://github.com/settings/tokens)
- Generate your GitLab `token` [here](https://gitlab.com/profile/personal_access_tokens)
- Gitter uses a custom integration URL specified in the planning file (details to follow below)
```bash
$ microplan login
```
### Initialize
`init` creates a file to help you get started with the planning flow
```bash
$ microplan init [filename].yml
$ microplan init --help
Usage: microplan-init [options]
Options:
-t, --template specify input template location
-d, --directory specify plan output directory
-h, --help output usage information
```
Yep, that's it! Open filename.yml to configure.
### Configuration
Configurations lie at the heart of microplan and help you specify the platforms you want to publish to (eg. which repository to create an issue in or which room to plan the discussion in)
```yml
feature: Create user registration form
description: "To persist user preferences ..."
configuration:
uxGitterChat:
type: gitter
url: "https://webhooks.gitter.im/e/xxxxxxxxxxxxxxxxxxx"
frontendRepo:
type: github
slug: "microplan-xyz/www"
backendRepo:
type: gitlab
slug: "microplan-xyz/api"
```
### Plans
The `plans` object is part of the same yml file and helps you express each step of your plan.
```yml
plans:
# Send a message to the UX team asking about the feature
- title: "How should the User Registration Page look like?"
description: "Should it have a dark or light theme? And would you suggest a specific font we should use?"
in: uxGitterChat
# Create an issue in the front-end GitHub repository
# And notify the UX team on Gitter
- title: "Choose frontend css framework for user registration page"
description: "Should we go with Bootstrap or Spectre? Please let us know about the benchmark. Prototype PRs can be sent here."
assignee: scriptnull
in:
- frontendRepo
- uxGitterChat
# Create an issue with a lengthy description in the GitLab repository
- title: "Support new user registration"
in: backendRepo
assignee: scriptnull
description: >
Add the `user-routes.js` file and use the Express router
```javascript
var express = require('express')
var router = express.Router()
// GET /user
router.get('/user', function (req, res) {
// fetch from DB
})
router.post('/user', function (req, res) {
// save in DB
})
module.exports = router
```
```
### Publishing
Once you have written the plan, use the `publish` command to create the issues and send messages to specified rooms
```bash
$ microplan publish [filename]
$ microplan publish -h
Usage: microplan publish [options]
Options:
-h, --help output usage information
-s, --serial Publish plans serially
-p, --parallel Publish plans parallely
```
¡Eso es todo!
* Your UX team will receive a Gitter notification
* the front-end issue will be created on GitHub
* the back-end issue will be created on GitLab
### Input Formats
The configuration file can be written in various formats.
| Format | Status |
|--------|--------|
| YAML | AVAILABLE |
| JSON | AVAILABLE |
### Contributors
Authored and maintained by [@scriptnull](https://github.com/scriptnull) and [@argonlaser](https://github.com/argonlaser) with help from [contributors](http://github.com/microplan-xyz/microplan/contributors).
### Attributions
Thanks to [these awesome npm packages](https://github.com/microplan-xyz/microplan/blob/master/package.json#L28-L42) without which the project would not have been possible.
### Security
Please report any security vulnerabilities of this project to [keybase.io/scriptnull](https://keybase.io/scriptnull)
```bash
$ curl https://keybase.io/scriptnull/pgp_keys.asc | gpg --import
```