Gerrit/New repositories

From MediaWiki.org
Jump to: navigation, search

This page is mainly about git repositories in general, but some of it is specific to MediaWiki Extensions as that is a very common use for a repository. All new extensions have Git repositories. If you want to be a Gerrit project owner (with +2 rights) of code that's already in Gerrit, use Gerrit/Project ownership. If you want to request an old SVN extension be moved to Git, ask here, and just mention the old repository in the comments.

Step 1: Get Git access[edit]

Access to Git is managed via Wikimedia Labs and integrated with Gerrit. You can get an account here.

There's information on Wikimedia Labs outlining how to access Wikimedia's Git installation once your account is setup.

Step 2: Use a compatible open source license[edit]

MediaWiki is an open-source project and users are encouraged to make any MediaWiki extensions under an Open Source Initiative (OSI) approved license compatible with GPL-2.0+ (Wikimedia's standard software license).

We recommend adopting one of the following compatible licenses for your projects in Gerrit:

For extensions that have a compatible license, you can request developer access to the MediaWiki source repositories for extensions. To specify the licence in code and with "license-name" a key should be used to provide it's short name, e.g. "GPL-2.0+" or "MIT" adhering to the list of identifiers at spdx.org.

Step 3: Review community expectations[edit]

A developer sharing their code on the MediaWiki wiki or code repository should expect:

Feedback / Criticism / Code reviews
Review and comments by other developers on things like framework use, security, efficiency and usability.
Developer tweaking
Other developers modifying your submission to improve or clean-up your code to meet new framework classes and methods, coding conventions and translations.
Improved access for wiki sysadmins
If you do decide to put your code on the wiki, another developer may decide to move it to the MediaWiki code repository for easier maintenance. You may then request commit access to continue maintaining it.
Future versions by other developers
New branches of your code being created by other developers as new versions of MediaWiki are released.
Merger of your code into other extensions with duplicate or similar purposes — incorporating the best features from each extension.
Credit
Credit for your work being preserved in future versions — including any merged extensions.
Similarly, you should credit the developers of any extensions whose code you borrow from — especially when performing a merger.

Any developer who is uncomfortable with any of these actions occurring should not host their code directly on the MediaWiki wiki or code repository. You are still encouraged to create a summary page for your extension on the wiki to let people know about the extension, and where to download it. You may also add the {{Extension exception}} template to your extension requesting other developers refrain from modifying your code, although no guarantees can be made that an update will be made if deemed important for security or compatibility reasons. You may use the current issues noticeboard if you feel another developer has violated the spirit of these expectations in editing your extension.


Step 4: Request a Git repository[edit]

You'll be telling us your Wikimedia Labs username, what code review model you want, what paths in trunk/branches/tags you want, what you want the project name in gerrit to be (and by implication the path to the project in gerrit, e.g. mediawiki/extensions/MyAwesome), and (if this is an existing Subversion repository) giving us a link to your community consensus that you want to move to git. Click request, then fill in the fields on the page creation screen:

Step 5: Commit your files[edit]

Once you have some files, you can commit them and continue your work utilizing Git.


Step 6: Publish an extension page[edit]

To autocategorize and standardize the documentation of your existing extension, please see Template:Extension. To add your new extension to this Wiki:



(For libraries, see Manual:Developing libraries.)

Templates to use[edit]

Callsign[edit]

Your repository will also be browsable in Phabricator's diffusion tool. Diffusion uses a short "callsign" to refer to a repository, e.g. EMFR for the MobileFrontend extension at mediawiki/extensions/MobileFrontend.

  • While gerrit remains our git master, request that someone in #wikimedia-devtoolsconnect create a diffusion callsign for your repo.

Step 7: Continue development and enjoy![edit]

You'll likely start to get reviews at this point for code style. You can get a jump on those by reading over coding conventions and security for developers, and making sure that your code follows these guidelines.

Find a couple of established MediaWiki hackers to look over your code and point out any flaws in it. For example, they may point you to another extension that is already in use whose functionality duplicates what you want, or could be easily extended to do what you want. In that case, you should work on the extension that is already available.

Getting notified of changes in your repository[edit]

Other people are probably going to want to submit patches to your repository, but it's not always easy to know when that happens. You can have new changes in your repository emailed to you by gerrit if you modify your Gerrit settings. If you want to be automatically added as a reviewer to each new patchset (or a subset by regex), add yourself to the Gerrit reviewer bot.

See also[edit]