github.com/LGUG2Z/story@v0.4.1/README.md (about) 1 # story 2 [](https://goreportcard.com/report/github.com/lgug2z/story) 3 [](https://codeclimate.com/github/LGUG2Z/story/maintainability) 4 [](https://codeclimate.com/github/LGUG2Z/story/test_coverage) 5 [](https://travis-ci.org/LGUG2Z/story) 6 7 `story` works as a layer on top of [meta](https://github.com/mateodelnorte/meta) to aid development, continuous integration, 8 testing, container building and deployments when working with meta-repos containing a large number of inter-dependent 9 `node` projects. 10 11 - [Installation](#installation) 12 * [Go Get](#go-get) 13 * [Homebrew](#homebrew) 14 * [Bash Completion](#bash-completion) 15 - [The .meta File](#the-meta-file) 16 * [The trunk `.meta` file](#the-trunk--meta--file) 17 * [The `story` `.meta` file](#the--story---meta--file) 18 * [`.storyignore`](#-storyignore-) 19 - [Commands](#commands) 20 - [Workflow Examples](#workflow-examples) 21 * [Starting a New Story](#starting-a-new-story) 22 * [Updating From Trunk Branches](#updating-from-trunk-branches) 23 * [Migrating Existing Branches to a New Story](#migrating-existing-branches-to-a-new-story) 24 * [Switching Stories](#switching-stories) 25 * [Merging Completed Stories](#merging-completed-stories) 26 + [Using the GitHub PR Merge API](#using-the-github-pr-merge-api) 27 + [Using Plain Git](#using-plain-git) 28 29 # Installation 30 ## Go Get 31 ```bash 32 go get -u github.com/LGUG2Z/story 33 cd $GOPATH/src/github.com/LGUG2Z/story 34 make install 35 ``` 36 37 ## Homebrew 38 ```bash 39 brew tap LGUG2Z/tap 40 brew install LGUG2Z/tap/story 41 ``` 42 43 ## Bash Completion 44 Add the following to your `.bashrc` or `.zshrc` 45 ```bash 46 PROG=story source /usr/local/etc/bash_completion.d/story 47 ``` 48 49 # The .meta File 50 ## The trunk `.meta` file 51 There are two types of `.meta` files used by `story`, which are both supersets of the `.meta` file used by 52 [meta](https://github.com/mateodelnorte/meta): 53 54 The `.meta` file for the overall meta-repo includes two extra keys, `artifacts` and `organisation`: 55 56 ```json 57 { 58 "artifacts": { 59 "api": false, 60 "app": false 61 }, 62 "organisation": "SecretOrg", 63 "projects": { 64 "api": "git@github.com:SecretOrg/api.git", 65 "app": "git@github.com:SecretOrg/app.git", 66 "lib-1": "git@github.com:SecretOrg/lib-1.git", 67 "lib-2": "git@github.com:SecretOrg/lib-2.git" 68 } 69 } 70 ``` 71 72 `artifacts` refers to projects that can be built and deployed, and should be set to `false` in the `.meta` file for a meta-repo. 73 74 `organisation` refers to the name of the organisation on GitHub where private repositories are hosted. 75 76 A JSONSchema for the trunk `.meta` file is available [here](meta.json). 77 78 ## The `story` `.meta` file 79 The `.meta` file for stories includes a number of extra keys on top of those introduced above: 80 ```json 81 { 82 "story": "story/auth-endpoint", 83 "organisation": "SecretOrg", 84 "projects": { 85 "api": "git@github.com:SecretOrg/api.git", 86 "lib-2": "git@github.com:SecretOrg/lib-2.git" 87 }, 88 "hashes": { 89 "api": "c917d416366a04f2ec62c2e8aaee5bc740d8c6aa", 90 "lib-2": "6bbe39ebe169c46eee7b2a6bc392e0b37e397a0e" 91 }, 92 "blastRadius": { 93 "api": null, 94 "lib-2": ["api", "app"] 95 }, 96 "artifacts": { 97 "api": true, 98 "app": true 99 }, 100 "allProjects": { 101 "api": "git@github.com:SecretOrg/api.git", 102 "app": "git@github.com:SecretOrg/app.git", 103 "lib-1": "git@github.com:SecretOrg/lib-1.git", 104 "lib-2": "git@github.com:SecretOrg/lib-2.git" 105 } 106 } 107 ``` 108 `story` refers to the name of the branch that will be checked out on any projects added to a story. 109 110 `projects` refers to the subset of projects that the story requires work to be done on. 111 112 `hashes` refers to the current commit hashes of each project at the time of a commit to the meta-repo. 113 114 `blastRadius` refers to projects in the meta-repo that can be impacted by made changes in the scope of the current story. 115 116 `allProjects` refers to the complete list of projects in the meta-repo. 117 118 This latter file is automatically generated and maintained by `story` commands. For example, adding or removing a project 119 to a story will update the `projects`, `hashes`, `blastRadius` and `artifacts` keys accordingly, and making a commit 120 across the meta-repo will update the `hashes` key before making a final commit to the meta-repo. 121 122 A JSONSchema for the `story` `.meta` file is available [here](story.json). 123 124 ## `.storyignore` 125 Optionally, a `.storyignore` file can be committed to the root of the metarepo containing the names of repositories 126 in which the `package.json` files should never be modified by `story`. Repo names should be separated by new lines. 127 Glob and regex patterns are not supported. The state of these repositories will still be tracked by the `.story` `.meta` 128 file. 129 130 ``` 131 # .storyignore 132 lib-3 133 legacy-app 134 ``` 135 136 # Commands 137 ``` 138 NAME: 139 story - A workflow tool for implementing stories across a node meta-repo 140 141 USAGE: 142 story [global options] command [command options] [arguments...] 143 144 VERSION: 145 0.3.4 146 147 AUTHOR: 148 J. Iqbal <jade@beamery.com> 149 150 COMMANDS: 151 create Creates a new story 152 load Loads an existing story 153 reset Resets all story branches to trunk branches 154 add Adds a project to the current story 155 remove Removes a project from the current story 156 list Shows a list of projects added to the current story 157 blastradius Shows a list of current story's blast radius 158 artifacts Shows a list of artifacts to be built and deployed for the current story 159 commit Commits code across the current story 160 push Pushes commits across the current story 161 unpin Unpins code in the current story 162 pin Pins code in the current story 163 prepare Prepares a story for merges to trunk 164 update Updates code from the upstream master branch across the current story 165 merge Merges prepared code to master branches across the current story 166 pr Opens pull requests for the current story 167 help, h Shows a list of commands or help for one command 168 169 GLOBAL OPTIONS: 170 --trunk value (default: "master") [$STORY_TRUNK] 171 --help, -h show help 172 --version, -v print the version 173 ``` 174 175 # Workflow Examples 176 ## Starting a New Story 177 ```bash 178 # navigate to your metarepo 179 cd ~/metarepo 180 181 # create the story 182 story create story/sso-login 183 184 # add the repoos you will be working on 185 story add login-service marketing-app 186 187 # stage the changes made by creating and adding to the story 188 meta git add -p 189 190 # make an initial commit across all the repos 191 story commit -m "add login-service and marketing-app, update package.json files" 192 193 # push branches in all story repos 194 story push 195 196 # open PRs linked to a central issue 197 story pr --issue https://github.com/SecretOrg/tracking-board/issues/9 198 ``` 199 200 ## Updating From Trunk Branches 201 ```bash 202 # load the story 203 story load story/email-login 204 205 # merge in changes from trunk on every repo in the story 206 story update 207 ``` 208 209 ## Migrating Existing Branches to a New Story 210 ```bash 211 # create a new story 212 story new story/otp-login 213 214 # merge in changes from other existing on every repo in the story 215 story update --from-branch feature/otp-login 216 ``` 217 218 ## Switching Stories 219 ```bash 220 # reset to the trunk branches 221 story reset 222 223 # load another story 224 story load story/sso-acl 225 ``` 226 227 ## Merging Completed Stories 228 ### Using the GitHub PR Merge API 229 ```bash 230 # load the story 231 story load story/sso-login 232 233 # make sure we have the latest from master 234 story update 235 236 ########## 237 # EITHER # 238 ########## 239 # reset the package.json dependencies to point to master 240 story unpin 241 242 ########## 243 # OR # 244 ########## 245 # pin the package.json dependencies to a specific commit hash 246 story pin 247 248 # archive the story manifest and reset the .meta file for merge 249 story prepare 250 251 # push final changes to the story branches 252 # still on branch story/sso-login at this point 253 story push --from-manifest story/sso-login --story-branch 254 255 # merge using the github pr merge api 256 story merge --github 257 ``` 258 259 ### Using Plain Git 260 ```bash 261 # load the story 262 story load story/sso-login 263 264 # make sure we have the latest from master 265 story update 266 267 ########## 268 # EITHER # 269 ########## 270 # reset the package.json dependencies to point to master 271 story unpin 272 273 ########## 274 # OR # 275 ########## 276 # pin the package.json dependencies to a specific commit hash 277 story pin 278 279 # archive the story manifest and reset the .meta file for merge 280 story prepare 281 282 # push final changes to the story branches 283 # still on branch story/sso-login at this point 284 story push --from-manifest story/sso-login --story-branch 285 286 # merge the story to the trunk branch across all story repos 287 story merge 288 289 # push just the repos that were changed in the story post-merge 290 # on master branch at this point 291 story push --from-manifest story/sso-login 292 ```