[[PageOutline]]

= Updating Bugzilla =

This page describes a process to update the Bugzilla instance running on [https://bugs.webkit.org/ bugs.webkit.org].

== Setup from Scratch == #setup-from-scratch

This section describes how to set up a merge environment from scratch.  If you already have a git-svn repo for `Websites/bugs.webkit.org`, you can skip to the [#setup-from-git-svn-repo Setup from git-svn Repository] section.

 * Subscribe to the [http://bugzilla.org/cgi-bin/mj_wwwusr?func=lists-long-full&extra=announce announce@bugzilla.org mailing list] to receive email for security updates and new releases.

 * Install git and git-svn.  If you have a modern Xcode on macOS, these are already installed.  If you're using MacPorts:
{{{
    sudo port install git-core +svn
}}}

 * Import `Websites/bugs.webkit.org` from the WebKit repository into a local git-svn repository.
{{{
    mkdir bugzilla.git
    cd bugzilla.git
    git svn init -T trunk/Websites/bugs.webkit.org http://svn.webkit.org/repository/webkit
    git svn fetch
}}}

 * Import the upstream Bugzilla git repository.
{{{
    git remote add -f upstream https://github.com/bugzilla/bugzilla.git
}}}

 * Create a local git branch to track the `upstream/master` branch.
{{{
    git branch --track upstream remotes/upstream/master
}}}

 * Create a `.git/info/grafts` file to provide artificial merge points between the two remote repositories.
{{{
# master v4.2.11 merge has parents of    master r174778                       and upstream tag release-4.2.11
4b64f382a2fc1fb4afbed5c9edc94ef2eb5c91eb 255573a4808ab531c9e8711e44e00b7b652075f3 3e1e67bed36bbe454c654f1e0a16ce73e724a5e0
# master v4.2.7 merge has parents of     master r174764                       and upstream tag release-4.2.7
985ca379414dd5b51eea47ea42d235e7546db7d8 09f74fe94c6d96846757181c358a0d42e2e73f51 7355bd53bc4b20e248550e5467142a79e9512fbc
# master v4.2.1 merge has parents of     master r173253                       and upstream tag release-4.2.1
09f74fe94c6d96846757181c358a0d42e2e73f51 873ce20171c99c92b9c83d0ebce1d2fc0eedbd5c 07c6bfa4cea83c8284b04add26729f552c93bafc
# master v3.2.3 merge has parents of     master r45519                        and upstream tag release-3.2.3
4b974c2db64b5e85e72498b0c43100e2ea380a48 355650f88422025d80d5b5ca7f908d653936556e 780da003de2a006fefa6310f073e3c6be0281a6d
# master v3.0.3 merge has parents of     master r44547                        and upstream tag release-3.0.3
355650f88422025d80d5b5ca7f908d653936556e e9b8dc46dc0a804f199a0b1c2dfa4d2112608c8a c21a45673aade4ddc65b28b8b5b8a5f76870c796
}}}

* Add new `origin` remote and push the repository.  NOTE: This is only a PLACEHOLDER.  This step does not currently work!
{{{
    git remote add origin git://git.webkit.org/bugzilla.git
    git push origin master
    git push origin upstream
    git push --tags origin
}}}

== Setup from git-svn Repository == #setup-from-git-svn-repo

Pull the repo from a central git server and set it up to do a merge.  In theory, this should be faster than the [#setup-from-scratch Setup from Scratch] section.

 * Clone the git repository.  NOTE: This is only a PLACEHOLDER.  This step does not currently work!
{{{
    git clone git://git.webkit.org/bugzilla.git bugzilla.git
}}}

 * Change directories into the git working directory.
{{{
    cd bugzilla.git
}}}

 * Set up git-svn remote:
{{{
    git svn init -T trunk/Websites/bugs.webkit.org http://svn.webkit.org/repository/webkit
    git svn fetch
}}}
 FIXME: Should be able to make this faster by pre-caching `remotes/origin/trunk` and `remotes/origin/trunk@74393`.

 * Set up tracking branch for upstream.
{{{
    git remote add -f upstream https://github.com/bugzilla/bugzilla.git
    git branch --track upstream remotes/upstream/master
}}}

 * Create a `.git/info/grafts` file to provide artificial merge points between the two remote repositories.  See above.

== Update ==

 * Update git-svn of `Websites/bugs.webkit.org` in svn.
{{{
    cd bugzilla.git
    git checkout master
    git svn rebase
}}}

 * Pull updates from the upstream repository.
{{{
    cd bugzilla.git
    git fetch upstream
    git fetch --tags upstream
}}}

== Merge ==

The instructions below assume that Bugzilla was previously merged to `release-4.2.11` and is being updated to `release-5.0.3`.

 * Merge a new release of Bugzilla using an upstream tag.
{{{
    cd bugzilla.git
    git checkout master
    git merge --squash --no-commit release-5.0.3
}}}

 * Clean up any conflicts when the merge is done.
  * To check if there were previously local changes on master:
{{{
    git diff release-4.2.11..master path/to/file
}}}
  * To check for current differences to the merge target:
{{{
    git diff release-5.0.3 path/to/file
}}}

 It's important to check for unwanted changes that sometimes result from doing a grafted merge, such as duplicate code.  By comparing the changes from current `master` versus the changes in the current working directory to the release being merged to, one can be sure there are no unwanted changes.

 This frequently happens when changes are made for a point update on a branch that don't match a change to trunk.  The git merge then doesn't know that it needs to remove those changes, so one ends up with duplicate code, or conflicted code that's slightly different, even though there was no difference to the previous release version.

 * Compare merged tree with the `release-5.0.3` tag to make sure there isn't any left-over cruft.  Remove any cruft found!
{{{
    cd bugzilla.git
    git diff release-5.0.3
}}}

 * Apply changes made to standard CSS skin to custom CSS skin.
{{{
    # TBD
}}}

 * Test the merged Bugzilla locally.
{{{
    ./checksetup.pl
    # TBD
}}}

 * Schedule downtime for the update.

 * Commit changes from git-svn repository to subversion.

 * Do the update.

 * Update grafts file for new version just committed.