Personal tools
gvSIG Desktop
gvSIG Desktop

Cached time 11/21/13 11:24:39 Clear cache and reload

 
Document Actions

gvSIG code contribution profiles

by Jorge Sanz last modified 2012-08-24 12:11

gvSIG code contribution profiles

Version: 1.0

Introduction

This document integrates the description of the different contributor profiles that can participate on the development of gvSIG, presenting at the end on a pretty schematic way the main workflows available when contributing software code to gvSIG.

Described profiles are:

  • External developer
  • Project developer
  • Maintainer
  • Reviewer
  • Tester
  • Software architecture support

Profiles

External developer

Any community member interested on contributing patches. He doesn't have to had a strong commitment with the project and he should be able to do small contributions without too much barriers.

Project developer

A developer with write permission on the whole gvSIG source repository or at some section. He is a developer strongly committed to the project, providing code regularly, so he needs to be comfortable committing changes.

To obtain this role a request to the TSC Board will be presented and will pass with simple majority if (s)he fulfil the established metrics. If the metrics are not fulfilled, the motion will pass with a qualified majority of 3/4. This role can be lost if a request to the TSC Board is presented and will pass with the same criteria that to get the profile.

Maintainer

It's the person in charge to any task to coordinate the development of a subsystem. They will deal with tickets from external developers, or reassign them to project developers. On the other hand, from a technical point of view they will take care to maintain a high cohesion and loose coupling in the subsystem they maintain.

To obtain this role a request to the TSC Board will be presented and will pass with simple majority if (s)he fulfil the established metrics. If the metrics are not fulfilled, the motion will pass with a qualified majority of 3/4. This role can be lost if a request to the TSC Board is presented and will pass with the same criteria that to get the profile.

Reviewer

Is the person in charge of the review and evaluation of the changes on the subsystems started by someone's request or because a periodic supervision.

He's objective is to maintain stability and robustness of the application as a whole, focusing specially on subsystem interfaces and the collaborations between them.

She is a developer with an special sensitivity that encourages her to look with criticism the code, looking more for the impact of changes on the system than on the usefulness of the functionality that code adds.

This profile doesn't requires specific knowledge on the module affected by any change, nor a deep knowledge on gvSIG architecture, and they won't be assigned to any specific subsystem inside gvSIG.

An important note in that a reviewer is not to support any module or subsystem maintainer at all. If you understood that, please read carefully the maintainer description.

To get or loose this profiles the same rules that for maintainers will be applied.

Tester

Note

This tester description is not complete, here there are relevant information about their relation with the other roles described on this document.

A tester is a person in charge of verifying that the application behaves on the way it is noted on a ticket. If the ticket is about a bug fix, it will contain the code, but also all the relative information about how to reproduce the error and how to verify it has been fixed. If the ticket is about a new functionality, it will contain a description of its requirements and how the tester can assure they are fulfilled.

To qualify for this profile an appointment by the testing manager is the only requirement.

Software architecture support

Is a member of the gvSIG software architecture team who can be asked by any developer for advice or help in assessing the impact of a given change.

gvSIG code point of view of every role

Every role related with the development and interaction with the source code of gvSIG has a different point of view of the project. It can be of high level or in-depth. For example, a high level perspective will see a gvSIG product as a set of subsystems that interact trough a group of well defined interfaces. A low level point of view is focused on a subsystem implementation. With this definition in mind, next table shows the roles points of view on the gvSIG code:

Role Visibility
Software architecture support They have a general point of view of the application, looking at it as a whole.
Maintainer He looks for his module code, as well as any API his module interacts
Reviewer He looks at interfaces or even methods. He evaluates the impact of changes on the semantics, interfaces, method signatures or their context.

Rights and Obligations

The following are the duties and rights of each of the profiles:

Role Rights and Obligations
External developer
  • To open new tickets attaching code patches.
  • To know about Contributions and patches to the gvSIG code recommendations
  • To know about coding conventions used by the project
  • When your contribution modifies any API, the corresponding javadocs will be updated accordingly
  • If your contribution breaks any existing automated test, they will be updated accordingly
  • If the package maintainer requests it, you will provide additional or updated tests in order to cover the new behaviour contributed
  • If your contribution changes the Graphical User Interface, the maintainer could ask for an update on the user documentation to accept the patch
Project developer
  • Create new tickets attaching patches or references to changes at source code repository
  • Commit code to the source code repository (always with a ticket assigned to the commit)
  • To know about Contributions and patches to the gvSIG code recommendations.
  • To know about coding conventions used by the project.
  • To know when is allowed to commit changes to the source code repository and when is not. The project managers will notify about this timing on mailing lists.
  • To know well the development documentation.
  • Any uploaded code will have updated also the javadocs.
  • If your contribution breaks any existing automated test, they will be updated accordingly. Likewise, you will provide additional or updated tests in order to cover the new behaviour contributed.
  • Provide to the testers all the information they could need to validate the change, as well as update the test cases (nowadays this last requirement is not possible by technical impediments, but it will be needed as soon as they are solved).
  • If the package maintainer requests it, you will provide additional or updated tests in order to cover the new behaviour contributed
  • If your contribution changes the Graphical User Interface, the maintainer could ask for an update on the user documentation to accept the patch.
Maintainer
  • Create new tickets attaching patches or references to changes at source code repository
  • Commit code to the source code repository
  • Assign tickets to reviewers
  • Ask to software architecture team about the impact of a code change
  • Assign tickets to developers to commit changes to the source code repository or to ask for more information to the community contributor. That doesn't avoids revision, it's just to speed up the process if it has to be done.
  • Auto-assign a tickets with an attached patch and commit it or ask for any change to the contributor. This doesn't remove revision, it just speeds up the process if it has to be done.
  • To assure that tickets have all the information needed by testers to validate the change, and if this is not true, to claim for it to the developer that contributed the change.
  • As a maintainer is also a project developer, (s)he will have the same rights and obligations besides their specific ones.
  • To assure that tickets received on his subsystem are treated accordingly (assign tickets to reviewers or to developers)
  • To reject tickets without updated javadocs if they are needed (always asking first to the developer if the first time they weren't provided)
  • To reject tickets that broke any automated test existing at the project of the contributed code (always asking first to the developer if the first time they weren't provided)
  • To reject tickets with code that doesn't follow the project code conventions (always asking first to the developer if the first time they weren't followed)
  • To reject tickets that don't specify how a tester can verify the change solves the incorrect behaviour (always asking first to the developer if the first time it wasn't provided)
  • Maintain the configuration, information and documentation about the building process of the subsystem. If maven is used, assure that besides compilation, deploy mechanisms are working, site generation, etc. as well as the information stored at pom.xml file: developers, description, etc.
  • Be responsible on the application on corrections and new functionalities between different live versions of gvSIG, at least against superior versions. It's not necessary to apply or ask for changes on all versions, but at least (s)he has to create the tickets in order to not lose the changes. For example, there is a bug with a patch for gvSIG Desktop 1.x, it should be applied or at least to create the corresponding ticket for 2.x.
  • He is in charge to maintain a high cohesion and loose coupling in the subsystem he maintains
  • He is in charge of the source code version control he maintains
  • He has to coordinate changes to be ready for next releases of the application
  • He has to be aware of the dependencies of the subsystem he maintains
  • He has to maintain the user documentation updated, asking to the ticket creator for additional information or needed screenshots
  • He has to know about the project procedures associated with the user documentation generation
  • He has to know about the procedures associated with the process of releasing a new version of the project, binaries naming, where they have to be placed, how to update libraries,....
Reviewer
  • Create new tickets attaching patches or references to changes at source code repository
  • Commit code to the source code repository
  • Accept or reject tickets with code contributions
  • Ask to software architecture team about the impact of a code change when knowledge of gvSIG as a complete systems are needed.
  • Ask the maintainer when the code contribution is related with a subsystem with an assigned maintainer.
  • Review assigned tickets
  • Report on the ticket any detected problem on the code
  • Reject any ticket that broke existing automated tests on the project where the changes will be applied.
  • Reject any ticket without the proper documentation (javadocs) on the code changed or contributed.
  • Reject any ticket with code that doesn't follow the gvSIG code guidelines
  • Reject any ticket with code but without instructions for the testing team about how to verify that code works as expected
  • Fix small problems that the code contribution can arise, annotating that on the same ticket
  • If the ticket is a patch an the change is accepted, commit it to the source code repository
  • Inform the maintainer when (s)he can not attend an allocated ticket for review
Tester
  • To mark a ticket as a non resolved
  • To mark a ticket as a non valid
  • To mark a ticket a validated
  • Review assigned tickets by the testing manager and mark them as validated, non solved or waiting for more information
Software architecture support
  • Assign tickets to be reviewed.
  • Assign tickets to the reviewers to be reviewed on a given version stabilisation period, on those modules where there is no assigned maintainer.
  • Attend developers help requests

Activities restrictions

Next table shows what is not allowed to every role.

Role Restricitons
External developer
  • To commit code directly to the source repository
  • To approve a ticket with a patch
  • To auto-assign a ticket
  • To validate a ticket
Project developer
  • To approve a ticket with a patch or code contribution
  • To assign tickets
  • To validate tickets
Maintainer
  • Review his own patches or code contributions
Reviewer
  • When accepting code, to take decisions about functionality
  • Review their own tickets
  • Commit code from a ticket that has not be assigned to him by a maintainer or the architecture team

Role metrics

Next table shows the different metrics to take in account to obtain a role.

Role To obtain a role
Project developer
  • Provide at least three code patches
  • Participate on at least two gvSIG product revisions
  • To exists at least two reviewers, maintainers or software architecture team members supporting the candidate, specially those reviewers that had worked on candidate contributions.
Maintainer
  • Participate as a project developer on at least the complete period between two gvSIG revisions.
  • Participate actively on the wanted module, at least with 6 (six) code patches.
  • To exists at least one reviewer, maintainer or software architecture team member supporting the candidate, specially those reviewers that had worked on candidate contributions.
Reviewer
  • Participate as a project developer on at least the complete period between two gvSIG revisions.
  • To exist at least one reviewer, maintainer or software architecture team member supporting the candidate, specially those reviewers that had worked on candidate contributions.

This table shows some considerations to be taken in account when losing a role:

Role To lose a role
Project developer
  • Provide at least four consecutive code patches rejected after their revision by a maintainer or reviewer
  • Inadvertently repeated contributions that cause other errors in the application
  • Two years of no participation
  • If there is a clear dissociation with the project
Maintainer
  • Provide at least four consecutive code patches rejected after their revision by a reviewer or a software architecture team member
  • Two years of no participation
  • If there is a clear dissociation with the project
  • Four or more contributions to a module of an specific version, without applying or creating a new ticket for the superior version
Reviewer
  • Provide at least four consecutive code revisions where the software architecture team considers that the API syntax or semantics has been altered, affecting the behaviour of any other part of the application
  • Two years of no participation
  • If there is a clear dissociation with the project
  • If there is a neglect of their duties clearly and repeatedly

Use cases and work flows overview

Warning

In development

Use case 1: new ticket with patch

  • A new ticket is created with the bug or new functionality despription
  • The developer adds a source code patch
  • If the ticket is managed by a reviewer:
    • The maintainer or architecture team member assigns the ticket to a reviewer
    • If the reviewer detects something wrong, he adds a note on the ticket and if he sees that the contributor would solve it, he asks for fixing at the same ticket
    • When the reviewer agrees with the patch, he commits it to the SVN and updates the ticket, changing the status to reviewed
  • If the ticket is managed by a maintainer
    • The maintainer or architecture team member assigns the ticket to a maintainer
    • The maintainer commits the changes to the SVN and updates the ticket
    • The maintainer or an architecture team member assigns the ticket to a reviewer
    • If the reviewer detects something that can be wrong, informs of this on the ticket and ask the maintainer about fixing it
    • When the reviewer is happy with the changes updates the ticket to reviewed
  • If the ticket is managed by a project developer
    • The maintainer or architecture team member assigns the ticket to the project developer
    • The developer commits the changes to the SVN and updates the ticket
    • The maintainer or architecture team member assigns the ticket to a reviewer
    • If the reviewer detect something that can be wrong, informs of this on the ticket and ask the developer about fixing it
    • When the reviewer is happy with the changes updates the ticket to reviewed

Use case 2: ticket management by a project developer

  • The developer will firstly contact the project maintainer using the ticket comments to inform about his interest on solving that bug
  • The maintainer assigns the ticket to the developer
  • The developer commits the changes to the SVN and updates the ticket
  • The maintainer or architecture team member assigns the ticket to a reviewer
  • The reviewer checks the code and if everything is ok changes to ticket to reviewed

Use case 3: ticket management by a maintainer

  • The maintainer assigns to himself the ticket
  • The maintainer commits the changes and updates the ticket
  • The maintainer or an architecture team member assigns the ticket to a reviewer
  • The reviewer checks the code and if everything is ok changes the ticket to reviewed
Change registry
version Description
1.1 Added information about the workflow (to be reviewed)

Powered by Plone CMS, the Open Source Content Management System

This site conforms to the following standards: