Manual:Pywikibot/Gerrit

From MediaWiki.org
Jump to: navigation, search
If you need more help on setting up your Pywikibot visit the IRC channel #pywikibotconnect @ freenode server or Pywikibot mailing list.

Terminology[edit | edit source]

  • Git - a version control system. Replaces SVN.
  • Gerrit - a code review platform (http://gerrit.wikimedia.org). Replaces Special:CodeReview
  • compat - formerly known as "trunk". If you're not sure, you probably use this.
  • core - formerly known as "rewrite".

For users[edit | edit source]

Git clients[edit | edit source]

For example in order to download core via commandline:

git clone --recursive https://gerrit.wikimedia.org/r/pywikibot/core.git

To update:

#Assuming we're already in "core"
git pull
git submodule update --force # Updates i18n messages

If you're lazy and want to be able to do that all at once, you can do:

git config alias.pullall '!git pull && git submodule update --init --recursive'  # You only need to do this once.
# Assuming  you're already in "core":
git pullall # This updates everything

(copied from [1]) [add --global to make this alias stick for all projects]

Note that the repositories are somewhat large (~70MB). If this is an issue, use

git clone --recursive --depth 3 https://gerrit.wikimedia.org/r/pywikibot/core.git

to just retrieve the latest versions.

Using SVN[edit | edit source]

But wait... I don't want to use Git. Can I still use SVN? Yes! For this example, I'm going to use pwb-core, however you can easily switch compat in.

svn co https://github.com/wikimedia/pywikibot-core/trunk
cd core/scripts # If you're using compat, change this line to "cd compat"
svn co https://github.com/wikimedia/pywikibot-i18n/trunk i18n

Updating is as simple as

svn up core/trunk
cd core/scripts # Again, compat is "cd compat"
svn up i18n

Note Note: Windows users may also use the GUI extension TortoiseSVN. You'll find the documentation here.

URLs[edit | edit source]

Your client will probably ask you for the repository url. The urls follow the format of: https://gerrit.wikimedia.org/r/pywikibot/[repo name].

So for compat: https://gerrit.wikimedia.org/r/pywikibot/compat.

So for core: https://gerrit.wikimedia.org/r/pywikibot/core.

Nightly distributions[edit | edit source]

You can download the whole packages or browse the source code via nightly distributor in Wikimedia Labs

For developers[edit | edit source]

How to submit patches...configure git/gerrit. etc.

Follow steps in Gerrit/Getting started and run this:

#for hacking core
git clone --recursive ssh://USERNAME@gerrit.wikimedia.org:29418/pywikibot/core.git

and after modifying codes follow steps in Gerrit/Tutorial

Windows
Developer using Windows may also use Gerrit/TortoiseGit tutorial for further informations.

Example (step-by-step)[edit | edit source]

So for example if you want to work with compat (formerly known as trunk), do the following, step-by-step:

  1. setup your software:
    1. if not done already for svn access; create an SSH key, a developer account and add your public key to gerrit as well as to wikitech
    2. install 'git' package
    3. install 'git-review' package
      • the one by openstack [2], NOT the one by Facebook
      • any version like 1.12, 1.21, but NOT v1.18
  2. clone and setup your repo:
    1. clone the git repo with all submodules by using (like svn checkout)
      $ git clone --recursive ssh://USERNAME@gerrit.wikimedia.org:29418/pywikibot/compat.git pywikipedia-git
      
      and wait, this step will take some time
    2. enter the directory
      $ cd pywikipedia-git
      
    3. config git setting for this repo/directory only (not global, in case e.g. you have different pseudo for multiple projects)
      $ git config user.email "EMAIL"
      
      and
      $ git config user.name "USERNAME"
      
      in order to configure this globally, use the --global parameter
    4. config your terminal/console to output english messages (in order to work properly with git review, see Gerrit/git-review#Troubleshooting)
      $ alias git="LANG=C git"
      
      this has to be done every time a new console is started, in order to configure this permanently, put this into your bashrc or similar setup file
    5. setup git review for this repo only
      $ git review -s
      
      and enter your USERNAME again, this is an important step - if you forget it, according to Gerrit/Tutorial#Push your change set to Gerrit, the final git review below (needed to commit your changes for review) will fail - though this can be still solved then
  3. work with the repo, e.g. commit patches for review:
    1. switch to the master branch (might not be needed)
      $ git checkout master
      
    2. update the current branch to revision online (like svn update)
      $ git pull
      
    3. create your own local temporary branch for working
      $ git checkout -b MEANINGFUL_BRANCH_NAME
      
      and try to choose a MEANINGFUL_BRANCH_NAME with the help of the branch naming tips available - the branch can be removed when not needed anymore with git branch -D MEANINGFUL_BRANCH_NAME
    4. now write some code; see the Git commands add, rm and mv to add, remove or rename files - when you're ready go to the next step
    5. commit your changes to your local temporary branch with
      $ git commit --all # In the Gerrit world you can do this only once per branch! Remember to follow the commit message guidelines.
      
      (you can use -a instead of --all and -R instead of --no-rebase) and, as used from svn, enter a meaningful commit message, e.g. a short description of your code changes
    6. optionally check your changes by looking at the committed data
      $ git show HEAD
      
      and make sure that you are sending what you wanted to
    7. send the data to the online repository, resp. gerrit for review (like svn commit)
      $ git review
      
    8. finally go to Gerrit, click on your change and write a reviewer name in the input box near the "Add Reviewer" button
  4. optionally/opt-in further settings:
    • enable RCS keywords expansion (like svn:keywords $Id$) by using git hooks (explained in detail here - german only)
      • for compat (trunk):
        $ git config filter.rcs-keywords.smudge 'maintenance/rcs-keywords.py %f'
        
        $ git config filter.rcs-keywords.clean 'maintenance/rcs-keywords.py'
        
      • for core (rewrite):
        $ git config filter.rcs-keywords.smudge 'rcs-keywords.py %f'
        
        $ git config filter.rcs-keywords.clean 'rcs-keywords.py'
        
      • (may be we should consider using the git-rcs-keywords module as mentioned in dealing-with-svn-keyword-expansion-with-git-svn)

Bugzilla[edit | edit source]

Patches will be linked to a bugzilla bug automatically if you mention 'Bug 12345' in the summary or 'Bug: 12345' on a line just before 'Change-Id: ....'

Problems, issues and work-a-rounds[edit | edit source]

jenkins-bot messages[edit | edit source]

https://integration.wikimedia.org/ci/job/pywikibot-core-pep8/46/console : FAILURE in ?s (non-voting)

The patchset committed did not pass PEP8 code style checks. That says nothing about the functionality of the code but about the style.

https://integration.wikimedia.org/ci/job/pywikibot-core-pyflakes/46/console : FAILURE in ?s (non-voting)

The patchset committed did not pass pyflakes code style checks. That says nothing about the functionality of the code but about the style.

This change could not be automatically merged with the current state of the repository. Please rebase your change and upload a new patchset.

The pachset cannot be merged automatically into current HEAD. Please consider Gerrit/Advanced usage#Build failed due to merge conflict for a solution.

More info about this can be found in Gerrit/Tutorial#How to submit a patch and Gerrit/Tutorial#git review complains about multiple commits.