GitHub Features
- You need to have Git and you need to have the Hub tool installed already.
-
$ phing feature-start(alias:$ phing feature) Can be used to start a new feature branch following the WebSharks Hubflow model. You must start from the000000-devbranch when running this command.$ git checkout 000000-dev $ phing feature-start # Then enter the issue number when prompted: 123- Validations occur first. Must be on dev branch, and it must be clean, etc, etc.
- Then, the latest dev branch is pulled from the remote so you're starting fresh.
- A new branch is created:
feature/123, based on the latest dev branch. - You are moved to that feature branch so work can begin.
By default, this command will also open a PR at GitHub for you. If you prefer not to do that, you can do:
$ phing feature-start -D pr=false. Also, by default, it will prompt you for an issue number to associate with the feature branch. If you'd like to bypass that prompt, do:$ phing feature-start -D issue=123, where123is the issue number passed via the command-line instead of through a prompt.$ git config --global alias.fs '!phing feature-start -D'$ git fs # Shorter and sweeter.$ git fs issue=123 # Note that -D is already in the alias.$ git fs pr=false # Note that -D is already in the alias.$ git config --global alias.fs '!f() { phing feature-start -D issue="$1"; }; f'$ git fs 123
-
$ phing feature-finishCan be used to finish a feature branch following the WebSharks Hubflow model. You must be on an existing feature branch when calling this command. The current feature branch will be deleted if all qualifying factors allow it, and you'll be moved back to the dev branch, with all the latest changes merged in from the remote origin. Feedback is provided at the command line should there be a problem.Note: Don't run this until you're completely done with all commits, and all of your work has been pushed, reviewed, and merged into the dev branch by the project lead; i.e., wait until the PR is closed. Then, you are ready to 'finish' the feature branch and remove it.
$ git checkout feature/123 $ phing feature-finish
- Validations occur first. The feature branch must be clean and it cannot exist remotely, etc, etc.
- If that checks out, you are moved back to the dev branch automatically and the dev branch is updated to the latest remote copy so you have a fresh starting point.
- Your local copy of the
feature/123branch is deleted to clean things up.
$ git config --global alias.ff '!phing feature-finish'$ git ff # Shorter and sweeter.
-
$ phing feature-finish -D force=trueCan be used to finish a feature branch following the WebSharks Hubflow model. You must be on an existing feature branch when calling this command. The current feature branch will be deleted if all qualifying factors allow it, and you'll be moved back to the dev branch, with all the latest changes merged in locally and then pushed to the remote origin. Feedback is provided at the command line should there be a problem.Note: This example uses the
force=trueflag, which states that it's OK to continue and finish the feature branch, even if the feature branch still exists at the remote origin. Theforce=trueflag also states that a local merge will always occur; i.e., your local feature branch will be force merged into your local dev branch with the--no-ffflag, and then your localdevbranch is pushed to the remote origin. When finished, if the feature branch still exists at the remote origin, it is deleted automatically (locally and remotely). In short, this allows you to run through the entire process of merging/pushing/finishing a feature branch, bypassing a typical PR merge at GitHub. Doing it locally instead.$ git checkout feature/123 $ phing feature-finish -D force=true
- Validations occur first. The feature branch must be clean, and it CAN exist remotely. If it exists remotely, your local copy of the feature branch must be up-to-date with the remote origin.
- If everything checks out, you are moved back to the dev branch automatically and the dev branch is updated to the latest remote copy so you have a fresh starting point.
- Your local copy of the
feature/123branch is merged into your localdevbranch. - Your local
devbranch is then pushed to the remote origin so that it's up-to-date. - Your local copy of the
feature/123branch is deleted to clean things up. - The remote copy of the
feature/123branch is deleted to clean things up.
$ git config --global alias.fff '!f() { phing feature-finish -D force=true; }; f'$ git fff # Shorter and sweeter.
Yes. Running $ phing feature-start from the dev branch will start a new feature, even if you already have other pending features that you're working on simultaneously. You can simply switch from one branch to another and work on multiple issues that way if you'd like. There's nothing in the software that prevents you from doing this.
It's easiest to work on one feature branch at a time, and when you're done, work on another one. However, there is a huge difference between being 'done' and actually 'finishing' a feature branch that you started previously.
In short, you don't need to 'finish' every single feature before you start a new one. It's important to realize that 'finishing' is only a formality. It's not a requirement in our workflow; i.e., 'finishing' is mostly about keeping your local repo clean and tidy. It's about you removing old feature branches that no longer exist at GitHub because they were merged in by the project lead after a review.
To help clarify the difference between 'done' and 'finished':
-
done = When I have made the changes, committed them, and pushed them for review; i.e., there is an open PR and it has a green build status. At this point, I will start a new feature branch and work on something else while I'm waiting for the project lead to review my work.
-
completely done ... I am not completely done until the project lead reviews my work and merges it into the official dev branch. When this occurs (if this occurs), I consider myself completely done with the feature branch. Until then, I need to keep a local copy of my feature branch in case I need to pull changes proposed by the project lead, or go back and make more changes to satisfy the project lead after a review.
-
finished ... Once I am completely done, I can go back and 'finish' the feature branch; i.e., delete it from my local repo by running
$ phing feature-finish. It's at this point that I consider myself to be completely done and finished with a feature branch. In fact, it no longer exists at this point, because running$ phing feature-finishdeletes the branch.
Note: If the project lead didn't like my work, or if there was a discussion and the general consensus is that the work I did is no longer needed and the PR was discarded — the feature branch was deleted remotely. That's fine too, and in that case I also consider it 'finished', because it's fine for me to run $ phing feature-finish and get rid of my local copy.
That's fine. To be honest, I don't run this command much myself. Instead, every now and then I'll do a review of my local repo and clean things up manually. I also have some aliases that I use to help tidy-up my local repos. So again, running $ phing feature-finish is only a formality. See previous FAQ for details.