DevFlow: ROADMAP/git based develop flow control =================================================== WARNING: Pre-alpha implementation for internal use only. Pre-Requirement ----------------- - A Bash command line console (cygwin is supported) - A workable git installation and `git` command in the path - Ruby 1.9.x Install ----------- $ [sudo] gem install dev_flow Work Flow ------------- Under you development working directory: 1. Write a `ROADMAP` file in a specified format 2. (Optional) create `members.yml` file define known developers 2. Run `dw` command Sub-commands for typical work flow jobs are: $ dw [info] # show task information $ dw progress 80 # mark the task as completed at 80 percent $ dw pg 80 # same as progress $ dw complete # mark that the implemention is completed $ dw close # this command is for project leader only, it will close the current task, # merge it into `develop` trunk and delete the git branch both # locally and remotely. $ dw release # like close but for release branch only. # the change will be merged into both `develop` and `master` branch. More commands may plug in later. ROADMAP File Format -------------------- The default task control file is `ROADMAP`, unless you specify an other file using $ dw --roadmap OTHER_FILE See more options by issue $ dw -h or $ dw --help ### Information Header Contents between two % --- (with a head `%` and at least 3 dashes) lines and before any definition of task will be treated as information header. Which should be in YAML format and should at least contains `title`, `leader`, and `team`, like: % --- title: A Sample Project status: producing members: qsh: [Qin Shihuang, 'qsh@qinchao.com'] leader: sunyr team: [huangw xuyc] year: 2013 % --- If you define `year` in the header, you can write date in `mm/dd` format instead of `yyyy/mm/dd`. Usually you should define developers in a separate `members.yml` file, but you can define extra members in the header area too (usually for who only join to one or few projects). ### Team and Leader Leader has a higher priority than team members, only leader can edit roadmap, close a task branch, and make a release, etc. If you also defines `supervisor`, `moderator`, they can update the roadmap too, but can not close or release a branch. IMPORTANT: those kind of permission is just introduced for avoid miss operation, NOT intended as a security mechanism. You still needs setup permissions on your remote git server if security is a concern. Generally you are encouraged to use short names in team members to save typings, by define a `members.yml` file in the following format: members: short_name: [Display Name, 'email@address.com'] This is also a way to avoid typos in ROADMAP definitions. ### The Task Tree Every line start with a `[+]` (or `[++]`, `[+++]` ...) will be treated as a task definition. A typical task definition line should following the format: [+] branch_name: taskname date/to/start[-date/to/stop] @resource[;resource] [-> dependent_on;dependent_on] - `[+]` one or more + in bracket is the indicator of task definition, one + represent a 1st degree (level) task, ++ represent a second degree task, .... Task degree with smaller number may contains several tasks with higher degree number. - `branch_name` must contains only a-z, 0-9, dot and underscore, which is used as git branch name, and also serves as a id for that task within the same ROADMAP file. - `taskname` could use any characters provide not contains 'date like' parts (see the next description). - `date/to/start` should in format 2013/03/03 or 03/03 if you defined `year` in the header (so you can specify only the `mm/dd` part). Use `mm/dd-mm/dd` (`yyyy/mm/dd-yyyy/mm/dd`) to specify a period. If the task duration is within one day, date/to/stop part can be omitted. - `@resource`: resource should correspond to leader or one of the team member. If the task need more than one resources use ; to separate them. - If the task depends on other task, puts their id after `->`. ### Git Branching Models - `master`, `develop`, `staging` and `production` branches are **trunks**. Code implementation and modification should be done in non-trunk branches and merged into trunks according the following roles. - The `master` trunk is a production ready branch, `develop` is the **integration** branch that contains latest code of completed feature that passed all integration test. - Development branches (**task branch**) should stem from `develop` often, and merged back into `develop` trunk as soon as the implementation complete and passed all unit and integration tests. - Release branches is purely for code review, test and necessary bug fix, after pass all of that, they will be merged into both `develop` and `master` trunk, and a `release-xxx` tag will be attached. ### Semantic Versioning and Special Tasks Tasks with branch name starts with `release_`, `hotfix_` ... will affect the version number. You use `release_` branch to manually manage major and minor versioning, e.g. `release_v0.1` will create a tag `version-0.1`, and hotfix branches will add-up fix numbers after it such as: `version-0.1.28`. All those branches will merged into `master` trunk. `milestone_` is a special type of task that corresponding to important event in the development flow (for example event for team code review, customer acceptance review, etc.), but do not affect version numbers, so do other tasks. Sometimes you may want to use 'prepare releases' such as `release_v0.1a`, `release_v0.1b`, avoid sandwich tasks between prepare releases and releases. Local Configuration --------------------- Default is stored in `.dev_flow` file and will be set to `git`'s ignore list (`.gitignore`) (so these settings only affect your local working directory). Without this file `dw` will go into the initialization mode (by asking you some questions). You can use `--local-config FILE` to store those information in an other file name. `.dev_flow` is also in yaml format and the most important key are `whoami` and `git_remote`, `whoami` specifies who is currently working on the local working directory, and `git_remote` defines witch git remote server to use (default is `origin`). With out `git_remote` the `dw` command will not try to communicate to remote git server. Command Details ------------------- - `dw init` default command if no `.dev_flow` file found. - `dw [info]` or `dw` without command will list the tasks and if the working directory is clean, let user chose to switch to working for known tasks. - `dw progress 0-98` set task progress. `dw pg` is an alias of `dw progress`. You are encouraged to frequently use this command to store you changes to remote servers (typically several times a day). - `dw complete` set task progress to 99 (complete a task), urge the leader to review/test and close it. - `dw close`/`dw release` close the task by the leader, or release it (to master trunk). - `dw update-roadmap` or `dw ur` used for update the roadmap (should only be used on `devleop` trunk). - `dw cleanup` will delete local branches corresponding completed tasks (TODO).