Skip to content

Commit

Permalink
Merge pull request #2325 from mythmon/bgb
Browse files Browse the repository at this point in the history 
Document git merge workflow.
  • Loading branch information
@mythmon
mythmon committed Jan 27, 2015
2 parents e06504b + 98d7bc5 commit d7e1050
Show file tree
Hide file tree
Showing 4 changed files with 85 additions and 82 deletions.
18 changes: 8 additions & 10 deletions docs/deployments.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,7 @@ The Source
==========

All of the source code for Kitsune lives in `a single Github repo
<https://github.com/mozilla/kitsune>`_. There are two important branches and we
use tags.
<https://github.com/mozilla/kitsune>`_.


Branches
Expand All @@ -29,24 +28,23 @@ Master
The ``master`` branch is our main integration points. All new patches should be
based on the latest ``master`` (or rebased to it).

Pull requests are created from those branches when they're "done".
Pull requests are created from those branches. Pull requests may be opened at
any time, including before any code has been written.

Pull requests get reviewed.

Once reviewed, the branch is rebased against ``master`` and then landed on
``master``.

Our `dev server <https://support-dev.allizom.org/>`_ runs ``master``, and it
updates every 15 minutes via a cron job.
Once reviewed, the branch is merged into ``master``, except in special cases
such as changes that require re-indexing. See
:ref:`Changes that involve reindexing <changes_reindexing>`.

We deploy to production from ``master``.


Dev
===

Dev runs whatever is in master and updates on every commit via github hooks
to an updater script.
Dev is a small environment that is updated manually. We use it primarily to
develop infrastructure changes, like uprading to Python 2.7.


Stage
Expand Down
2 changes: 2 additions & 0 deletions docs/development.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,8 @@ For questions that aren't answered there, ask someone and/or try
Googling the answer.


.. _changes_reindexing:

Changes that involve reindexing
===============================

Expand Down
124 changes: 60 additions & 64 deletions docs/patching.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,19 +30,17 @@ The Quick and Dirty
===================

Very quick, very little explanation. Those with strong git fu may already see
some shortcuts. Use them! As long as ``mozilla/master`` doesn't have merge
commits, it's all good.
some shortcuts. Use them!

Assuming your Github account is ``foobar`` and you've already forked Kitsune::
First, clone your fork, and then point the master branch to Mozilla's fork.
Assuming your Github account is ``foobar`` and you've already forked
Kitsune::

git clone git@github.com:foobar/kitsune
git clone https://github.com/foobar/kitsune
cd kitsune
git remote add mozilla https://github.com/mozilla/kitsune.git
git fetch mozilla
git checkout -b temp
git branch -d master
git checkout -t mozilla/master
git branch -d temp
git checkout -t mozilla/master -B master

If you haven't set up your local git user, please do before committing any code
for Kitsune. This way you can take credit for your work::
Expand All @@ -53,36 +51,36 @@ for Kitsune. This way you can take credit for your work::
You should only need to do that once. Here's the bit to do every time::

git checkout master
git pull --rebase mozilla master
git checkout -b my-feature
git reset --hard mozilla/master
git checkout -b my-feature-123456

# Make a change and commit it.
$EDITOR path/to/file.py
git add path/to/file.py
git commit -m "[Bug 123456] Fooing and the Barring."
git push origin my-feature
git push --set-upstream origin my-feature

# Open a pull request, get review.
# Respond to feedback:
$EDITOR path/to/file.py
git add path/to/file.py
git commit -m "Feedback from Barfoo"
git push

# r+! Rebase and squash.
git checkout master
git pull --rebase mozilla master
git checkout my-feature
git rebase -i master # Squash any feedback commits.

If you don't have commit access::

git push -f origin my-feature
# DONE
Eventually you'll get an r+. If you have commit access, now you can go ahead
and merge your branch. You may, if you want, rebase your branch to clean up
any embarassing mistakes, but it isn't required. If you don't have commit
access the next part will be done by someone who does.

If you *do* have commit access::
There are two options. The first is to press the Big Green Button in GitHub PRs
that says "Merge pull Request". If you would prefer to do it manually (or
if there are merge conflicts, you can do this::

# r+! Merge
git checkout master
git merge my-feature # Should be a fast-forward commit.
git fetch mozilla
git reset --hard mozilla/master
git merge --no-ff my-feature-123456
git push mozilla master # Bots will alert everyone!
git push origin master # Optional but nice.

Expand Down Expand Up @@ -117,11 +115,8 @@ You should avoid changing your ``master`` branch, it should track
``mozilla/master``. This can help::

git fetch mozilla
git checkout master
git checkout -b temp # Create a temporary local branch.
git branch -d master # Delete your local master.
git checkout -t mozilla/master # Create a tracking branch.
git branch -D temp # Delete your temporary branch.
# Update your master branch to track Mozilla's master branch instead.
git checkout -B master -t mozilla/master # Update your master branch to

If you haven't set up your local git user, please do before committing any code
for Kitsune. This way you can take credit for your work::
Expand All @@ -132,13 +127,12 @@ for Kitsune. This way you can take credit for your work::
The correct way to keep your local master up to date is::

git checkout master
git pull --rebase mozilla master

You can avoid typing ``--rebase`` every time by doing::

git config branch.master.rebase true
git fetch mozilla
git reset --hard mozilla/master

More actual code in a minute!
This will forcibly move your local master branch to whatever is on the Mozilla
master branch, destroying anything you have commited that wasn't pushed.
Remember to always work on a branch that is not master!


Find a Bug
Expand All @@ -149,7 +143,6 @@ Bugzilla bug to track the work for all the involved teams. There are `a number
of open bugs <http://bit.ly/LUTjcY>`_ if you want to try your hand at fixing
something!


New features or changes to features need bugs to build a consensus of
developers, support team members, and community members, before we decide to
make the change. If you want to change something like this, be sure to file the
Expand All @@ -164,7 +157,9 @@ To make sure no one else is working on the bug at the same time, assign it to
yourself in Bugzilla. If you have the proper permissions there's an easy "take"
link next to the Assignee field. Ask in the IRC for details.

You don't need to bother setting the bug to the ``ASSIGNED`` state.
You can assign bugs to yourself even if you aren't going to immediately work on
them (though make sure you will get to them sooner rather than later). Once you
are actively working on a bug, set the bug to the ``ASSIGNED`` state.


Fix the Bug on a Branch
Expand All @@ -178,13 +173,15 @@ Fix the Bug on a Branch
All bug fixes, changes, new features, etc, should be done on a "feature
branch", which just means "any branch besides ``master``." You should make sure
your local ``master`` branch is up to date (see above) before starting a new
feature branch.
feature branch. Your feature branch should include the bug number in the branch
name, if applicable.

::

git checkout master
git pull --rebase mozilla master # Update local master.
git checkout -b my-feature-branch # Some logical name.
git fetch mozilla
git reset --hard upstream/master # Update local master.
git checkout -b my-feature-branch-123456 # Some logical name.

Now you're on a feature branch, go ahead and make your changes. Assuming you
haven't added any new files, you can do::
Expand All @@ -205,7 +202,7 @@ Github so you can open a pull request.

::

git push origin my-feature-branch
git push --set-upstream origin my-feature-branch

Then, in your browser, navigate to
``https://github.com/<yourname>/kitsune/compare/my-feature-branch`` and hit the
Expand All @@ -215,6 +212,12 @@ filled out enough for you to submit it right away.
We add an ``r?`` in the pull request message indicating that this pull
request is ready to go and is looking for someone to review it.

Othertimes you may want to open a pull request early that isn't quite ready to
merge. This is a great way to share the work that you are doing, and get early
feedback. Make it clear that your PR isn't ready by putting ``[WIP]`` in the
title. Also make sure to say when it is ready! The best way to do this is to
remove ``[WIP]`` from the title and make a comment asking for ``r?``.


Respond to Review
-----------------
Expand Down Expand Up @@ -245,61 +248,54 @@ There may be more than one round of feedback, especially for complex bugs. The
process is exactly the same after each round: make the changes, add them in yet
another new commit, push the changes.

There are also a few bots that might interact with your PR. In particular, our
continuous integration service will run tests and style checks on your new
code. All PRs must be approved by the CI system before they will be merged,
so watch out. They show up as either a red X or a green check mark in the
PR.


Ready to Merge!
---------------

Once a pull request has gotten an ``r+`` ("R-plus", it's from Bugzilla) it's
ready to merge in. At this point it should be rebased against the current
``mozilla/master`` and any feedback/fixup commits should be squashed.
ready to merge in. At this point you can rebase and squash any feedback/fixup
commits you want, but this isn't required.

If you don't have commit access, someone who does may do this for you, if they
have time.
have time. Alternatively, if you have commit access, you can press GitHub's
"Merge pull request" button, which does a similar process to below. This is the
preferred way to merge PRs when there are no complications.

::

git checkout master
git pull --rebase mozilla master
git checkout my-feature-branch

# Update and squash.
git rebase -i master

git reset --hard mozilla/master
git merge --no-ff my-feature-branch-123456
# Make sure tests pass.
python manage.py test
git push -f origin my-feature-branch
git push


You're done! Congratulations, soon you'll have code running on one of the
biggest sites in the world!

If you do have commit access, you should land your patch!

Continuing from above::

git checkout master
git merge --ff-only my-feature-branch


This requires that the merge be a fast-forward only. If it's not, then the merge
will fail and you'll have to rebase.

Before pushing to ``mozilla/master``, I like to verify that the merge went fine
in the logs. For the vast majority of merges, *there should not be a merge
commit*.

::

git log -5 # Verify that the merge went OK.
git log --graph --decorate
git push mozilla master # !!! Pushing code to the primary repo/branch!

# Optionally, you can keep your Github master in sync.
git push origin master # Not strictly necessary but kinda nice.
git push origin :my-feature-branch # Nice to clean up.

This should automatically close the PR, as GitHub will notice the merge commit.

Once the commit is on ``mozilla/master``, copy the commit url to the bug
in Bugzilla and close the pull request.
Once the commit is on ``mozilla/master``, copy the commit url to the bug.

Once the commit has been deployed to stage and prod, set the bug to
``RESOLVED FIXED``. This tells everyone that the fix is in production.
23 changes: 15 additions & 8 deletions requirements/dev.txt
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,32 @@
# These requirements are helpful, but not required, for working on Kitsune.

# sha256: a_c6l7D-RUKn7i2KYnoTs4KegdERvidVGzag36DCkJk
q==2.4
# sha256: 6U6syZbt8Rq7o3Lw3APp2PHQCIn9KeiTXE6bvZuir9w
django-debug-toolbar==1.2.2

# sha256: ku47hrXBkhwtnawhe--JkMX4Usi8TZAYyv4PPzuBzTo
nosenicedots==0.5
# sha256: Y6KG6ssDzV9kPX60WMbGK3DBEbRjT9jVnyfMrKS3yDo
django-sslserver==0.14

# sha256: KF6L1zDAtv374jwy0pNr_7pAHyPKsTLocixovoDW8YI
flake8==2.2.5

# sha256: WioXDkfeVZOmq_rh6VQr0sOSSsYrvk5u2WyVPANSJDo
mccabe==0.2.1

# sha256: ku47hrXBkhwtnawhe--JkMX4Usi8TZAYyv4PPzuBzTo
nosenicedots==0.5

# sha256: ZrOLKZ3UoMt2qFXnvNxkDc4rGfXdFkpW7oeuMWQrUy0
http://people.mozilla.org/~wkahngreene/pep8/pep8-1.6.0a0-willkg.1.tar.gz#egg=pep8==1.6.0a0-willkg.1

# sha256: P6gKELNtUWhr93RPXcmWIs1cmM6O1kAi5imGiq_Bd2k
pyflakes==0.8.1

# sha256: Y6KG6ssDzV9kPX60WMbGK3DBEbRjT9jVnyfMrKS3yDo
django-sslserver==0.14
# sha256: a_c6l7D-RUKn7i2KYnoTs4KegdERvidVGzag36DCkJk
q==2.4

# sha256: lJM7ZOL-CAfaBhLFdKAhwNrCjHvTxKI3I65aOeqPPQQ
Sphinx==1.2.3

# sha256: x9txeBCraWX2bIzwOYqYydjfmC2jm0zX8WKRHriVlvo
docutils==0.12

# sha256: 6U6syZbt8Rq7o3Lw3APp2PHQCIn9KeiTXE6bvZuir9w
django-debug-toolbar==1.2.2

0 comments on commit d7e1050

Please sign in to comment.