RFC Move To Github Issues And Wiki

Ralph Schindler edited this page Sep 19, 2012 · 13 revisions

By: Ralph Schindler


Currently, there is a disconnect between where we host our issues and where the code lives. Our canonical issues are still (as it was in ZF1) located in JIRA http://framework.zend.com/issues/. Github has a built in issue tracker and wiki that the ZF2 repository currently has turned off.

The disconnect is that by using an external tool like Jira, we lose out when it comes to these various aspects:

  • linking of a new issue to the codebase in the form of component/path affected
  • linking of a proposed/pull request fix to an existing issue
  • 2 separate discussions can now happen, in different places
  • Jira encourages patches, whereas Github encourages fork/edit/pull

While there is less of a disconnect on the wiki, there are fewer people utilizing the wiki on a regular basis. This is primarily due to the fact that to document developer processes, we've trended towards putting README files into the actual repository. For the few interactions we have where we need a wiki, github wiki suits our needs.



Jira is a fantastic product when used in conjunction with its other suite of tools: Confluence, Crowd and Crucible. One of the problems with Jira is from an organizational standpoint: running any of the Atlassian tools requires some knowledge of how Java and the JVM works, especially in a public facing, high traffic, single server environment. The Zend Framework team has periodically had to delve deep into Atlassian toolset to fix issues that occasionally crop up; this tends to put a strain on the team as there are few people with few cycles that know enough about Java/JVM/Atlassian to effectively administer these applications.

Additionally, the drastic and fundamental changes that are happening within the Jira and Confluence product lines make upgrading to newer versions a major blocker. Specifically: newer versions of Confluence no longer utilize nor store wiki formatted code, and plugins we use such as the voting plugin no longer work, meaning we lose all voting records. Since newer versions of Jira require newer versions of Confluence in order to bridge the products, we're stuck with the inability to upgrade either.

Existing Jira Features

Issue Tracker:

  • Following basic information: Subject, Body, Discussion, Code Linking, Status/Resolution, Reporter, Type of Issue
  • Complex:
    • Milestones
    • Assignment to individual
    • Component Affected
    • Affected Versions
    • Workflows:
      • Apply patch to multiple branches
      • Build passed
    • Priority and Planning
    • Watching
    • Voting
  • Reporting:
    • Unresolved issues
    • Specialized list of issues (by search or explicit list)
    • New Since [Yesterday,Week,Year,...]
    • Fixed in Release
  • Actions
    • automatic (or semi-automatic) assignments based on criteria


  • Standard wiki features
  • Vote tracking module
  • Hierarchical Pages / Sections
  • Page workflows/templates

Missing Features In Github

Issues: // We could use tags for some of this @Maks3w

  • Component Affected
  • Affected Versions?
  • Priority?
  • Voting (But Adding A comment has been a common workflow)
  • Reporting:
    • Specialized list of issues?
  • Actions:
    • automatic assignment
  • Linking pull requests to existing issues


  • Voting (though this could be moved outside the wiki)
  • Page workflows
  • Only a single namespace

Gained Features From Github

  • Social nature (Fits with our code platform philosophy)
  • Built-in userbase
  • Well known platform
    • known featureset and workflows
  • Issues:
    • Direct connection between Issues and Code/Pull-Request
  • Wiki:
    • wiki is also a git repository

Proposed Path Forward

Porting Issues

  1. Turn on Github Issues
  2. Create corresponding labels for issue tags
    • labels for components
    • labels for type? (feature, defect, etc)
  3. Ensure milestones are correct
  4. Write script to pull issues from Jira an insert into GitHub
    • Map component to labels
    • Assign to correct assignee
    • Give all issues default milestone
  5. Visit issues and triage


Porting Wiki

  1. Determine which content needs to be exist in the wiki.
  2. Flatten structure to work within GitHub


  • Should we consider a non-GitHub issue tracker like dokuwiki and self-host?
  • Should we port both ZF1 and ZF2 content?
    • Is there any readily used content in ZF1 that needs to be ported? (Translator pages?)
    • Can all ZF1 Proposals go away? (Since no new features are allowed on the ZF1 tree, closing all but accepted proposals may make sense.)