Updated useful information in the README

[DavidLiedle]

Now that we're starting to settle in to a workflow, we can update the instructions for community members to participate. :)

[andrerom]

Do we need to use branches for versions? Aiming a version this early in the process (at the start of specification stage) is bound to be miss for most cases, and is harder* to adapt then if we use milestones which we are in control of.

Personally I would rather have gone for:

• progress tracked on project board, version is using milestone that can change
• feature branch until given feature is fully accepted (and imho when ENG/Contributor capacity is allocated)
  • So either merge to master once reviewed and accepted by all parties (PM, QA, ENG, Community), or stage after by Contributor(s) when they get starting on it and can start to line up with the WIP tech spec in the repo where code will go

* UI here allows you to switch base branch, but you'll have to rebase to avoid taking with you other changes in the branch you switched from to the one you switch to.

[DavidLiedle]

@andrerom - TL;DR: Yes, we do.

Longer version: The ultimate goal of every branch is to be merged into master. Whether that takes 6 minutes or 6 months is of no concern, as well as whether or not it is ever merged at all or abandoned (in the case of some prototypes).

We do use feature branches, but haven't had time to write it down yet. The PM team has discussed, agreed, and been trained on this approach. We toyed with the idea of switching the base branch, and even did so for a brief experiment. That was a fail, and we learned from it. The simplest solution is the best: master is the currently-recommended-product, and is default. Things in the future are in feature branches (if it helps to think of v2.0.0-alpha as a feature, then it is also a "feature branch" to which individual PMs, Engineers, and Community members may submit pull requests). Things in the past are (will be) in tags.

This allows a fine-grain view across the entire line of products and DX solutions, as a Pull Request shows only the files which are different whilst keeping them in the exact same familiar product hierarchy.

So either merge to master once reviewed and accepted by all parties (PM, QA, ENG, Community), or stage after by Contributor(s) when they get starting on it and can start to line up with the WIP tech spec in the repo where code will go

That's roughly what we're doing. Think of the branch v2.0.0-alpha as "master" for the v2 project. Things are merged there only after review by all parties. Eventually it will march through -beta, -rc1, and then GA. When it is the currently-recommended-product (stable, or LTS, depending on when we no-longer-recommend v1.x), it will become master.

Explaining it makes it seem complicated, but the workflow is simple:

• Check out the branch you want to affect (e.g., v2.0.0-alpha)
• From that, create your own branch with a useful name
• Do your work, save, add, commit, push
• Open a Pull Request <<-- Discussion/Review/Cross-Team-Approval occurs here

Boom. PM takes it from there.

[andrerom]

As discussed yesterday even if I think involving versions (in our case often fixed to a specific date) during spec phase is un-agile, lets define spec for this to surface which use cases / requirements made you want to use versions here.

Cause if we take your example it would rather be:

1. Orientate yourself between master / future branches / open PR's for existing features to decide if you need to create a new feature or suggest changes to exiting one
2. Among the features in the given version identify the feature you want to affect
3. Check out the branch you want to affect depending on where you found it above (e.g., featureset-v2.0)
4. From that, create your own branch with a useful name
5. Do your work, save, add, commit, push
6. Open a Pull Request <<-- Discussion/Review/Cross-Team-Approval occurs here

As opposed to a feature branch approach closely aligned with how we work on code as well:

1. For existing accepted features you'll find them in A. master, or B. for WIP you'll find it among pull requests (PR also directly placed on board to keep it simple) with prefix "[Epic] Feature X"
2. Check out the branch you want to affect depending on where you found it above (e.g. A: master, B: feature-x)
3. same..

And thats before we even start to deal with how much more hassle there will be dealing moving a feature from one version to the next, or merge conflicts because the branches are tired to versions and thus might change semantics of several features at once.

So I still prefer a feature first view, but besides maybe being to ambitious to try to use this in place for Epic board, lets as mentioned try to surface the requirements for dealing with versions here in the first place later today.