RFC Move To Github Issues And Wiki
Clone this wiki locally
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
- Following basic information: Subject, Body, Discussion, Code Linking, Status/Resolution, Reporter, Type of Issue
- Assignment to individual
- Component Affected
- Affected Versions
- Apply patch to multiple branches
- Build passed
- Priority and Planning
- Unresolved issues
- Specialized list of issues (by search or explicit list)
- New Since [Yesterday,Week,Year,...]
- Fixed in Release
- 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?
- Voting (But Adding A comment has been a common workflow)
- Specialized list of issues?
- 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
- Direct connection between Issues and Code/Pull-Request
- wiki is also a git repository
Proposed Path Forward
- Turn on Github Issues
- Create corresponding labels for issue tags
- labels for components
- labels for type? (feature, defect, etc)
- Ensure milestones are correct
- Write script to pull issues from Jira an insert into GitHub
- Map component to labels
- Assign to correct assignee
- Give all issues default milestone
- Visit issues and triage
- Do we port closed issues? I tend to think not.
- Porting and coding missing features can mostly be attained by leveraging an API developed by myself:
- And the web-app consuming this API: http://hardcoreforking.org/zendframework/zf2/pulls/
- Determine which content needs to be exist in the wiki.
- 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.)