Being a package owner
From Symbian Developer Community
Contents |
About the Package Owner role
Package owner is an evolving role with several core aspects.
The key aspect of the role is acting as a software change gatekeeper. All code changes to a package go through the respective package owner.
Another essential aspect is interfacing between the contributors, community and Symbian Foundation. For most, this will mean "wearing several hats" - at the outset this will be their employer's one and the Symbian Foundation one. The third, community "hat" is equally important for encouraging community contributions, but also for getting help in managing a package - package owner can designate a support team and decide on different classes of contributors.
Responsibilities of a Package Owner
Working with the community
Symbian foundation is an open source organisation and package owners are in a unique position to harness the potential of the community in improving the code and documentation. There are several key responsibilities that lay with the package owner in this respect.
First, package owner is responsible for the package's public face. All packages have a home page, wiki and documentation sections on the Symbian Foundation web site. Maintenance can be delegated, but is ultimately the responsibility of the PO. This is quite important - apart from the PR perspective, good package documentation can encourage contributors and make PO job easier.
Package owner can also delegate some tasks through a Package Support Team. The support team can be selected from contributors and aid in many tasks - from maintaining wiki, reviewing code to doing build/test tasks. Setting up and running a support team is entirely up to the package owner.
Managing contributions
Managing contributions is a key responsibility for the package owners. This applies to a varity of contribution types - new features, code improvements and refactoring, defect fixes, but also code reviews, documentation improvements and ideas.
There are several paths for contributing code changes.
- Direct commits (by committers)
- Contributions via Feature Branches
- Contributions via Patch files
These are discussed in more details below.
Direct commits
All package owners have write access to their package's master repositories. The package owner can designate additional Committers with the same write access. The ultimate responsibility for the package contributions remains with the package owner, but committers are trusted to maintain quality in their submissions. For more details about choosing committers, see Selecting Committers.
Contributions via Feature Branches
Feature branches are named branches, open to contribution from everyone. These are typically used for adding new features and hence the name.
Package owners don't have responsibilities regarding feature branches. They may, however, receive request to merge the content, fixes or featues into MCL. They may, at their own initiative, review feature branches and merge content to MCL when appropriate. This will typically be done by pulling the branch in the local repository, merging / building / testing and when all is good pushing back to Symbian Foundation MCL/RCL repository.
Contributions via Patch files
Bug fixes and minor features can be submitted using patch files. Each such submissions must have a Bugzilla entry (one or more). Patch files are normally submitted as attachments in Bugzilla bugs. Symbian Foundation Bugzilla can be found here.
Package owner's main responsibility for this contribution scenario is to review and apply the patch if the patch is in order. A typical workflow would be as follows:
- Run a Bugzilla report for your package for bugs in the "Proposed" state, or set up email notification when the bug enters "Proposed"
- Find the attached patch and declarations
- Review the diffs in the patch
- Apply the patch and commit change
- Test the change as necessary
- Push the change from your repository to the Symbian master copy
Gatekeeping
There are several key concerns when reviewing contributions. Here is a guideline on the decision process on whether and when to include a particular contribution:
- Reason for change
- Will the change make things better?
- Don't change things without a good reason. A valid reason is not always an important reason: removing remarks, refactoring, code formatting can all be valid reasons.
- Is the change technically sound?
- What level of code review is required?
- How deep is the change?
- Is the accompanying text accurately describing the change?
- Is a design review and build/test cycle required?
- What level of code review is required?
- License, authorship, export control
- All contributors must have a signed contribution agreement (in paper)
- The contributor must declare whether they own the copyright to the entire contribution
- If there are any restrictions to what Symbian Foundation can do with the contribution, the package owner must consult Symbian Foundation Legal team.
- Cryptography and Export control
- If the change adds any cryptographic capabilities, Package owner must consult Symbian Foundation Export Control Officer.
- Package specific criteria
- These are defined by the package owner.
- Is now the right time for this change
- Is the package building OK?
- Any downsides to committing now? Later?
- Consider carefully wider environment - package owner must be able to justify the decision.
- Is additional work required
- Code review, build/test cycle etc.
- Decision : Commit, Defer or Reject
- Commit if all is good and it is a good time for the change
- Defer if all is good, but the time is not right or something else must happen first
- Must review again when the time comes
- Reject if there is something wrong with the contribution
Package releases
Definitions
| SCM | Term Definition |
|---|---|
| Codeline | A set of files that evolve collectively. One codeline can be branched from another, allowing each set of files to evolve separately. |
| Branch | (noun) A codeline created by copying another codeline, as opposed to a codeline that was created by adding original files.
(verb) To create a copy of a codeline. |
Mercurial can have many repositories each of which has its own complete copy of a Package’s source files. Each repository contains one or more Package codelines, each of which can be named. The “line of development” within a codeline will be captured in a sequence of changesets or revisions (both terms are valid) made to Package files. At various points, changes can be pulled from one codeline to another or a branch can be created from a codeline. During a codeline’s evolution, selected revisions can be tagged as releases.
Package Codeline Management
There are three types of codelines:
- Master Codeline (MCL): stable, ongoing “line of integration”
- Control the timing & quality of the features & fixes that are gradually integrated into it
- Release Codeline (RCL): very stable, high quality, low risk “line of stabilisation”
- Control the timing, quality & types of changes that are allowed to integrate into it
- Feature Codeline (FCL): an initial (possibly unstable) “line of development”
Package Release Management
A common package release numbering scheme ensures consistency & understanding across Packages. The current package numbering scheme is a proposal and currently not approved by the Symbian Foundation Council. In the interim, all packages should comply with the proposed scheme as oulined below.
 | Warning Package version number is not yet in use |
The proposed Symbian Foundation numbering scheme uses a three-number versioning mechanism for packages:
<major>.<minor>.<patch>
Rules for numbering are as follows:
- <major> is always numeric, starting from 1
- <minor> is always numeric, starting from 0
- <patch> is alphanumeric starting from “a” for the first pre-release of <major>.<minor>, moving to 0 for the completed release, then incrementing to 1, 2 etc for maintenance releases.
Example sequence = 1.2.0, 1.2.1, 1.2.2, 1.3.a, 1.3.b, 1.3.0, 1.3.1, 2.0.a, 2.0.0, 2.0.1
Version numbers are changed as follows:
- Major Release: a new version with disruptive new features and/or architecture
- Minor Release: a new version with incremental, non-disruptive feature growth
- Patch Release: a new version with fixes & minor changes
The meaning of versions
Version indicates the backwards compatibility & content intentions of each version.
A new <major> version is probably incompatible with previous <major>:
- Breaks may be in Public and/or Platform APIs and must be approved by Architecture Council.
- This is a major content upgrade and it contains disruptive feature growth.
- Requires significant migration, integration and/or test effort to move up to this version
A new <minor> version is probably compatible with previous <minor>:
- But may have breaks in Platform APIs if approved by Architecture Council
- This is a minor incremental update and it contains non-disruptive feature growth & fixes
- Requires low integration and/or test effort to move up to this version
Compatibility baseline is set when <patch> becomes numeric – e.g. 2.0.0
Limitations of the current scheme
Current versioning scheme is a linear numbering scheme, however our codelines can split off into different branches.
The current scheme can only work if:
- A <major> MCL has a succession of <minor> releases and possibly some <patch> releases
- And each RCL taken off the MCL only has a succession of <patch> releases
What if you need to add functional growth to the RCL of a <minor> release?
- Either its forbidden as a <patch> release means it can only contain defect fixes
- Or the <patch> definition doesn’t set content limits & it can include some functional growth.
If you allow new <minor> releases on an RCL then you have more problems
- You have broken the linear sequence & the compatibility statements are impossible to meet
Package Roadmap
Package Owners define their Package roadmaps. Roadmap should consist of a planned series of features that will become available within a particular “timebox” (e.g. 3-month agile development release).
Package Owner will need to decide how to deliver each timebox of features:
- In a single new Minor release?
- In multiple new Minor releases?
- In a single new Major release?
- In a combination of the above?
Decision depends on number of features & how disruptive they are. Package owner will also need to show the impacts these decisions have on the roadmap, e.g. some features may only be available on the new Major release.
An FAQ on how to create a "Package Backlog" can be found here.
Codeline Policy
Package Owners are in charge of the codeline policy for their package. Therefore, they decide on:
- When & where to merge changes from an FCL into the Controlled Repository
- When : Do the changes meet MCL/RCL quality criteria – i.e. ready to be integrated?
- When : Is it the right time for the changes to go straight into a Major MCL (e.g. are they needed for current “in development” release)?
- Where : Should the changes go straight into an RCL – e.g. contains fixes only?
- Where : Do you need to create an RCL at the same time (e.g. to support patch releases for a “completed” release)?
- Where : Or should you put the changes in a new Major MCL (e.g. to support two separate Major versions to aid migration to disruptive technology)?
Package Version Release Lifecycle
Package Version Release Lifecycle consists of three states:
Experimental State
An experimental version only exists in an FCL and may not be a fully integrated version even there – i.e. it could be a combination of several FCLs. Therefore the version is not declared yet within the MCL repository since it may not yet meet criteria for move to Development state.
If a new <Major> version is being developed, “Experimental” Package releases for shared development, may be available from a branch within the FCL Repository.
If a new <Minor> version is in the pipeline features & fixes for it could be on various branches within the FCL Repository.
Criteria for moving from Experimental to Development state are the same as contribution criteria - both at Symbian Foundation and package level.
Development State
A Development version only exists in an MCL and may be doing some pre-releases from there. Version is ready for system integration:
- But does not yet meet criteria for move to Release state.
- It has a designated <major>.<minor> version number
- It has declared one or more pre-releases by tagging Package files within the MCL Repository
- Various features & fixes are gradually being pulled into MCL to be included in this version release.
Decision to move from Development state to Release state should be based on quality, functional completeness and the timing alignment with platform releases.
Release State
A Release version is first declared in MCL. Patch releases from the MCL can continue for as long as there is no need to merge in content for the NEXT release into that MCL. Once unwanted content comes into MCL (e.g. a new feature outside the version scope) then further patch releases can be done from a RCL.
Version is released and is ready for hardening when:
- It has been declared as a functionally complete <major>.<minor>.0 release within the MCL Repository
- It may be doing regular <patch> maintenance releases, depending upon its take-up.
- It may be branched from an MCL into a Release Codeline (RCL) branch if it needs to be protected from MCL submissions for next version release.
Multiple Major Versions
Some Packages will have roadmaps that lead to disruptive feature growth. In these cases, Package Owner may choose to release a new Major version.
Package Users can choose to use previous Major version (+ latest Minor updates) or migrate up to using new Major version, or use both – older Major version for some products, the newer one for others.
Some Package Owners will need a codeline strategy that can support continued development of multiple Major versions. Symbian Foundation SCM will achieve this by having a separate MCL for each Major version.
There will NOT be any code sharing between Major MCLs. Changes on an older Major MCL will need to be propagated to the newer Major MCL(s). Package Owners will need to weigh risks of single MCL vs costs of multiple MCLs.
Symbian Foundation Platform Releases
Platform configuration
A Platform configuration comprises a set of packages taken from any package codeline. The selected package versions must form a coherent Platform build, coherent at build time, ROM-build time and run-time. In order for this to happen, dependencies between package versions must be known.
Symbian Foundation builds a number of Platform configurations.
One important instance of platform configuration is Standard Device Platform Release (SDPR). The SDPR is defined by a platform configuration, and can evolve by updating package versions or adding / removing packages.
Platform build requires a Platform definition which lists which packages and package versions are included in the build. This information is stored in Mercurial, in it's own Platform repository along with other platform specific meta data. The source files are collected from multiple Mercurial repositories. Generated binaries are stored in a Platform Build Archive and are available to use as the base environment by other Package builds.
More information on Platform Build can be found on the Symbian Foundation Builds page.
SDPR Lifecycle
SDPR releases are timeboxed and take place twice a year.
The current proposal for managing integration risk in a SDPR project is:
- Gradually bringing in new Package versions when they are available as pre-releases depending on whether they are new Major or new Minor releases
- Working with Package Owners to ensure all selected Package versions eventually get to Release state by the end of the Final Phase
- Ensuring latest fixes go into the SDPR by keeping up-to-date with Patch releases
Below is an example for a Package with two Major versions – an established v1 that is undergoing some incremental feature growth and a new v2 that is getting ready for its first release. From SDPR perspective, the earlier SDPR may not want the risk of configuring in the new v2 late on its Integration cycle – especially as its not due to get to Release state until after the Final Phase. On the other hand, the later SDPR could push to include new v2 as a way of promoting the new technology & helping the community to migrate to it. However if the new v2 proves unstable or does not complete in time, the later SDPR has option of falling back to v1.
Note that decisions to fall-back or migrate up will always need to bear Package dependencies in mind – as its quite often not a single Package decision and the result of falling back to an earlier Package version may result in much of the rest of the Platform also having to fallback.
SDPR Integration Planning and Tracking
Few points regarding integration planning and tracking:
- Package Owners will collaborate with SF staff that manage SDPR integration
- SDPR Release Manager will support the SDPR planning & tracking work
- Review SDPR roadmaps & Package roadmaps
- To ensure alignment & mutual awareness of plans
- Agree which Package version to include in an SDPR timebox
- Time & Quality are intended to be fixed – so scope is the variable
- Intended Package version (with intended scope) may not end up being actual one included
- Track SDPR integration progress
- Which Package versions are included in the current SDPR configuration
- Latest status of SDPR builds, quality & any dependency/integration issues
- Latest SDPR milestone and what implications this has on Package development.
Managing Mercurial Repository
Information on Mercurial can be found in the Mercurial for Package Owners guide:
(for more general information on mercurial see Find Out More About Source Code and Mercurial). For help, please use the discussion forums.
Defect management
Information on defect management can be found on the Defect Handling Guidelines page.
Further reading
- Package Owner Admin Tasks: This page describes common administrative tasks, such as requesting a mailing list, etc.
Comments
Sign in to comment…
