Islandora Committers Workflow

Rosemary Le Faive edited this page May 5, 2017 · 8 revisions
Clone this wiki locally

Terms

  • User: Anyone who uses Islandora whether or not they participate in the community directly.
  • Contributor: Anyone who contributes in any form to Islandora (code, documentation, posts on the lists, etc).
  • Committer: Individuals with merging privileges, and binding votes on procedural, code modification, and release issues, etc. (further outlined here).
  • Component Manager: defined below.
  • Maintainer: Same as Component Manager.
  • Release Manager: Individual who oversees the development, testing, documentation, and deployment of a release.
  • Interest Groups: Islandora Interest Groups are those Islandora Community Members that come together around a particular topic relevant to the Islandora ecosystem.
  • Community: All of the above.
  • Internal: Refers to work done within a single organization.

Roles and Responsibilities:

  • Component Managers (group)
    • Component Manager (also known as “Maintainer”)
      • Interested in and/or familiar with the module; acts as a point of contact for the module. Encourages discussion about changes to the module when needed.
      • Ideally, there will be at least two Component Managers per module.
      • NOT a blocker on commits - they should comment, but their comment is not necessary to proceed.
      • NOT responsible for all bug fixes.
      • Tag interested parties on a module if they have not been tagged already
      • Should be a Watcher on the repo for their module, and subscribed to the Islandora user and developer listservs.
      • Welcome new contributors, and ask people who are contributing without a CLA to sign a CLA. And point them to contributing.md, if needed.
      • Not necessarily a developer
    • Release Duties:
      • Be available for communication about release issues, tickets, pull requests, etc, during the course of a release.
    • Term Limits
      • Will be asked if they want to remain as a component manager on a per release basis.
  • Committers (individuals) (outlined here)
  • Committers (group)
    • Only ones with merge permissions
  • Roadmap/Board: Defined by the Islandora Foundation.

Workflow Merging:

For automatic linking between JIRA tickets and Github pull requests, branch names and commit messages should follow Islandora's Git Guidelines and Best Practices

General Guidelines:

  • Identify if a JIRA ticket is needed:
    • Minor grammar / php warning: no ticket required
    • Feature or Fix beyond the minimal: JIRA ticket and PR Template
      • JIRA options:
        • Bug: Something is not working as intended
        • Improvement: Improvements to existing functionality
        • New feature: Completely new functionality
        • Code Task: Maintenance in the code; update to new standards; deprecate code; audit across modules
        • Task: A goal to be accomplished, outside of other definitions.
        • Documentation: Improve existing documentation; Document something new; correct mistakes in documentation. Refers to documentation in any context, including the wiki, GitHub, GUI, and inline in the code.
    • Unsure: JIRA ticket and PR Template. It is always better to err on the side of making a ticket.
  • Prioritizing pull requests:
    • If there is an urgent need for the pull request to be addressed quickly, indicate the need in the pull request or a comment.
    • Complexity should also be taken into account when evaluating how quickly to merge a pull request. Changes that affect core modules or make extensive changes should receive more review and testing.
  • All interested parties should be satisfied before something is merged; no hard numbers. If you know who is likely to be interested, tag them. Tag the creator of the JIRA ticket if possible. Make a reasonable effort.
  • If a pull request goes more than a week without response when one is needed, tag @Islandora/7-x-1-x-committers with a reminder.

Merging Workflow:

  1. JIRA ticket created describing the issue and/or intended solution

  2. Person taking on ticket, assigns it to themselves, and click ‘Start Work’

  3. Pull request issued based on template

  4. JIRA - click ‘Ready for Review’

  5. If bug, mark as ‘Fixed’

  6. If code task, feature, improvement, mark as ‘Done’

  7. Add link to pull request

  8. Review & QA (open to all)

  9. Consensus (disagreement -> binding vote)

  10. If unsure, summarize what you understand to be the consensus and ask for objections.

  11. Merge or close the pull request

  12. Pull requests should only be closed by the one who issued them, or if there is consensus for closing the pull request.

  13. When closing a pull request, there should always be a comment explaining the reason.

  14. Pull requests should not be merged by anybody who committed code within a given pull request or by another employee of the same organization (i.e. internal merges).

  15. If there are no outstanding concerns about the pull request, and the code has been sufficiently tested, and interested parties have been given sufficient time (24 hour window minimum) to respond to the pull request, then any Committer who feels confident with the code change (excluding those who would be considered ‘internal’ by the definition above) may merge the pull request.

  16. JIRA issue (by whoever merged the pull request)

  17. Make sure fix version is appropriate

  18. If bug, make sure Affects Version is applied

  19. Make sure appropriate components are added

  20. Close the ticket

Disagreement:

  • Any changes that are made to the code base, which members of the community (be they Committers or not) feel is not in the interest of the wider community, can be raised as an issue on one of the many channels of communication (Google groups, IRC, Interest Group Meetings, Committers Meetings, Roadmap etc). If the change is found not to be in the interests of the community it can be either reverted or iterated upon. The JIRA ticket should be reopened.

Merging during releases:

  • Time constrained, forcing greater pressure on all parties: person who created pull request, committers, component managers, reviewers, and release manager.
  • A JIRA must exist for each pull request to determine whether or not it should or should not go into the release branch.