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-tox-flake8/2591/console : FAILURE in ?s (non-voting)

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

https://integration.wikimedia.org/ci/job/pywikibot-core-tox-flake8-docstrings-mandatory/560/console : FAILURE in ?s (non-voting)

The patchset committed did not pass mandatory pep257 code style checks. That says nothing about the functionality of the code but about the inline documentation.

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

The patchset committed did not pass pre-merge test suite. That indicates the code fails the basic tests, but a pass says nothing about the functionality of the modified code. There is a more extensive set of tests which developers should run pre-submission, and will run post merge.

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.