Story Branches

!!! DRAFT !!!

TODO:

• Find a better name story branches/feature branches/bigfeat branches

User stories are a different concept that don't include DIPs. Feature OTOH is a very unspecific word that's overloaded with different concepts and somewhat vague on the scope. Also the common git workflows already use the name feature for small PRs (see Starting_as_a_Contributor).

User Stories

One or multiple software features that implement a D Enduser story (wish). User story - Wikipedia A good story states what is desired, not how it should be implemented. This distinction is important to avoid premature fixation on certain approaches without considering alternatives.

Talk to upstream maintainers, e.g. on the D.internals planning meetings (dates in dlang Calendar), before starting to work on a feature. Also make sure you get a mentor/reviewer/supervisor that feels responsible for your story and has enough time, otherwise you risk to get stuck later on.

Developing on Story Branches

• This guide assumes the usual dlang repo layout with upstream pointing to git://github.com/dlang/$repo.git and origin to git@github.com:user-name/$repo.git, also see Starting_as_a_Contributor. It also uses the shell variable `STORY=myStoryName` and `GHUserName=MyGithubUserName` throughout the examples.

• Create or ask a core member to create a set of equally named branches in the upstream (github.com/dlang) repos. They should be branched of from master.

 for proj in dmd druntime phobos tools dlang.org installer; do
   pushd $proj
   git fetch upstream
   git branch $STORY upstream/master
   git push --set-upstream upstream $STORY
   popd
 done

• Implementing something.

 cd dmd
 git checkout $STORY
 $EDITOR src/mars.d
 ...
 # usual git commit workflow
 ...
 # pushing to your own clone as with any other PR branch
 git push origin $STORY

• Regularly merging with upstream branches.

Whenever you feel that you reached a milestone, make an appointment with your mentor/reviewer/supervisor, and open a pull request. This PR should merge the $STORY branch in your fork into the $STORY branch on upstream.

Here is a small bash snippet to print the right urls to preview such a pull request.

 for proj in dmd druntime phobos tools dlang.org installer; do
   echo https://github.com/dlang/$proj/compare/$STORY...$GHUserName:$STORY
 done

Reviews for those should be coarser and rather merge friendly. At this stage the main purpose of reviews is to identify architecture and design flaws early on. Please avoid any nitpick discussions during development. It's the responsiblity of the mentor/reviewer/supervisor to streamline the development process of stories.

• CI testing

PRs against upstream story branches will have the same CI testing running as any other PRs. The CI systems will test your PR against the current $STORY branches of all upstream repos, just like any PR targeting master/stable is tested against the master/stable branches of all upstream repos.

• Syncing with master

Occasionally you might want to get other work from master into your story branches, in particular when you story branches get very old. This is achieved by merging upstream/master into your branches.

 for proj in dmd druntime phobos tools dlang.org installer; do
   pushd $proj
   git fetch upstream
   git checkout $STORY
   git merge --no-ff upstream/master
   # resolve merge conflicts
   git commit # as usual
   git push origin $STORY
   popd
 done

Resolving merge conflicts might mean including figuring out what other work on master could (semantically) collide with your work. If unsure ask your mentor/reviewer/supervisor for advise. The mentor/r/s is also responsible to avoid major collisions between different stories, still they might not always be avoidable.

• Preview builds

Previews builds can easily be created for story branches, iff the CI tests pass, just ask the Release Team. This tool should be used to get early feedback on the story.

• Final review/testing

Make sure to organize a final review and testing with your mentor/reviewer/supervisor when the story is nearing completion. This will be an open review/testing according to the full standards held for any other PR (including nitpick discussions). The mentor/reviewer/supervisor should be responsible for ensuring that architectural and design issues don't make it to this stage.