DeveloperDocumentation
|
Size: 3181
Comment: notes from bof
|
Size: 6731
Comment: use cases wanted, apparently (!)
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 5: | Line 5: |
| * See https://launchpad.net/distros/ubuntu/+spec/developer-documentaqtion | * See https://launchpad.net/distros/ubuntu/+spec/developer-documentation |
| Line 11: | Line 11: |
| == Interpretation and overall plan == | == Use cases == |
| Line 13: | Line 13: |
| During the first UBZ BOF, we concluded that the best way to achieve this would be to: | Alexander wants to help to translate his favorite application "hello" to his native Bohemian, but he doesn't know anything about where to start and where to look. Barbie wants to become a Universe Developer (MOTU) but she doesn't know how to start to work on a Debian-format package. Camilla has just started as a new Canonical staff member working on Ubuntu and is lost in a maze of twisty incomplete wiki pages trying to figure out how Ubuntu's processes are supposed to work. == Approach == We have concluded that the best way to achieve this would be to: |
| Line 17: | Line 26: |
| As well as deleting or replacing Debian-specific content from the DDR, we will transfer content from process-related wiki.ubuntu.com pages. | As well as deleting or replacing Debian-specific content from the DDR, we will transfer content from process-related wiki.ubuntu.com pages and add additional information as seems relevant. |
| Line 21: | Line 30: |
| == Areas to cover (or consider covering) == | The UDR should be kept up to date as processes change. |
| Line 23: | Line 32: |
| * BreezyReleaseSchedule (don't copy content, refer to it) * DeveloperResources (which should become a navigation page if not be completely deleted) * Different approaches to packaging, eg: `debian/rules` approaches (by-hand, debhelper, cdbs); patch systems (whether to use one, which one to use). * Who to talk to to decide whether to make a particular change/upload - areas of responsibility * Describe seeds and germination |
== Content == |
| Line 29: | Line 34: |
| == BOF notes from Thursday == | The list below is a list of topics to cover and a sketch of the content for each one. The organisation of the content will be that from the DDR, with appropriate additions, so not necessarily in the order listed here. |
| Line 31: | Line 36: |
| say at top which ubuntu release the doc describes the processes for | In many cases the exact details of the information to be included will need to be discovered by the UDR author by trawling the wiki and/or asking around eg on IRC. |
| Line 33: | Line 38: |
| how to build package - ubuntu-specific packages - ubuntu diffs from debian packages - syncs - package removals |
=== Specific topics and processes to cover === |
| Line 39: | Line 40: |
| When to make changes - who to contact for advice / input / info about correct change to make fine to make change covered by own area of responsibility for other things probably best to ask someone how to find out who last touched package compatibility problems / needed changes to other packages / communications - who to tell how after you've made your change / patch (what to do with patch) - who to ask before uploading (freezes, universe vs. main) - what to do after upload - expect email - check build logs How we handle translations |
The top of the UDR will say which Ubuntu release the document relates to, and how to find versions for other releases (so that it is straightforward to have different process documents for eg breezy vs. dapper) |
| Line 54: | Line 42: |
| wiki/DeveloperResources becomes link list and referred to in document | The UDR will document when and how to make ftp-master requests including syncs and package removals, including how to contact the ftp-masters. |
| Line 56: | Line 44: |
| chroots | The method used to determine the set of packages included in main and on the CDs will be documented including documentation about seeds and germination (with references to the appropriate revision control branches and germinate output logs). |
| Line 58: | Line 46: |
| patch systems etc. | We will say who to talk to to decide whether to make a particular change/upload: that you should usually just go ahead and make change covered by own area of responsibility (which may be a package, or some cross-package property), and that for other things it's probably best to ask someone. We'll explain how to find out who last touched a package. The UDR will warn about what to do for changes that may cause compatibility problems or require corresponding changes to other packages. |
| Line 60: | Line 48: |
| how to handle bugs (bug handling practices bof) |
In particular, we will say who is responsible for various important subsystems, including at least the following: * kernel team, #ubuntu-kernel * docs team, #ubuntu-docs * universe packages, #ubuntu-motu |
| Line 63: | Line 53: |
| tools people might find helpful pbuilder sudo lintian / linda piuparts |
If you need advice, input or permission, the UDR will give you an idea of who to contact, or at least how to find out who to contact. |
| Line 69: | Line 55: |
| Who is responsible for various important subsystems - kernel team, #ubuntu-kernel - docs team, #ubuntu-docs - universe packages, #ubuntu-motu ...? |
There will be information about freezes including who to contact about freeze exceptions, and reference will be made to BreezyReleaseSchedule (and successors). |
| Line 75: | Line 57: |
| How to merge new Debian or new Upstream or external Repositories merge-o-matic How to import from Debian |
We will describe what you should do after uploading, including where (if anywhere) to send copies of your patch, and what emails to expect and logs to check to see that all went well. |
| Line 80: | Line 59: |
| backports where to find them how to be nice to backporters who runs backports |
We will explain how to handle bugs, either by referring to the bug handling practices wiki page or preferably by incorporating the results of that UBZ BOF into the UDR. |
| Line 85: | Line 61: |
| When to not make changes - freezes how to get upload rights main vs universe (ref) motu wiki.ubuntu.com/REVU |
There will be some documentation about how to get upload rights, including references to policy documents about registering GPG keys in launchpad, the differences between universe and main, and references to MOTU processes including wiki.ubuntu.com/REVU. |
| Line 94: | Line 63: |
| get rid of introdeveloperdocs (at least, not have it in main) (also is Ubuntu-native with wrong version) |
There will be a brief discussion about how we handle translations (in particular how we do it differently to Debian) and a reference to Rosetta and langpack documentation. There will be some information about Ubuntu backports, including where to find them, some comments about how to be nice to backporters, and information about how to contact the backport team. === Information to be moved from elsewhere === Content should be transferred from DeveloperResources (which should become a navigation page), and the UDR will link to DeveloperResources. The package introdeveloperdocs (currently awaiting review) contains some not entirely accurate content and should be abandoned/rejected. (Also, it has an incorrect version number for an Ubuntu-native package.) === Information about packaging and uploading === Several topics about the construction of packages need to be covered, including: The differences in metadata between unmodified Debian source packages, Ubuntu-specific source packages, and Debian packages modified for Ubuntu. The different approaches to packaging will be covered briefly, including specifically common approaches to constructing `debian/rules`, such as straightforward construction by-hand, debhelper, and cdbs; we will make some recommendations about when to use and when not to use these particular tools (eg, that most Gnome packages use cdbs). Patch systems will also be described, and some advice given about whether to use one and which one to use. We will cover dpatch and cdbs at least, as well as reviewing manual approaches. We will describe how to merge new versions from Debian, upstream or external repositories and discuss merge-o-matic. There will be a brief discussion of the use of chroots and we'll also briefly mention other useful tools including pbuilder, sudo, lintian/linda and piuparts. == Implementation plan == We will focus on producing a useable UDR (by replacing Debian-specific information in the DDR) as soon as possible. The resulting draft UDR will be made available to all Ubuntu developers as work proceeds on the additional Ubuntu-specific content. Where new content is not Ubuntu-specific, we will supply it to the DDR maintainers via the usual Debian channels. Arrangements will be made for the current versions of the UDR to be given a stable URL, and of course links will be made from appropriate places. |
Status
Summary
We should have well-organized developer-oriented documentation for our various tools and procedures, including freeze exceptions, merge-o-matic, seeds and their germination, and much, much more.
Use cases
Alexander wants to help to translate his favorite application "hello" to his native Bohemian, but he doesn't know anything about where to start and where to look.
Barbie wants to become a Universe Developer (MOTU) but she doesn't know how to start to work on a Debian-format package.
Camilla has just started as a new Canonical staff member working on Ubuntu and is lost in a maze of twisty incomplete wiki pages trying to figure out how Ubuntu's processes are supposed to work.
Approach
We have concluded that the best way to achieve this would be to:
Create an Ubuntu Developers' Reference, which would be derived in the usual way (with a ubuntuNN version etc.) from the Debian Developers' Reference.
As well as deleting or replacing Debian-specific content from the DDR, we will transfer content from process-related wiki.ubuntu.com pages and add additional information as seems relevant.
The Ubuntu Documentation Team will of course be consulted, but the UDR will be maintained primarily by Ubuntu developers since (a) much of the proposed (non-Debian) content is currently known only to Ubuntu developers and (b) the audience consists of Ubuntu developers.
The UDR should be kept up to date as processes change.
Content
The list below is a list of topics to cover and a sketch of the content for each one. The organisation of the content will be that from the DDR, with appropriate additions, so not necessarily in the order listed here.
In many cases the exact details of the information to be included will need to be discovered by the UDR author by trawling the wiki and/or asking around eg on IRC.
Specific topics and processes to cover
The top of the UDR will say which Ubuntu release the document relates to, and how to find versions for other releases (so that it is straightforward to have different process documents for eg breezy vs. dapper)
The UDR will document when and how to make ftp-master requests including syncs and package removals, including how to contact the ftp-masters.
The method used to determine the set of packages included in main and on the CDs will be documented including documentation about seeds and germination (with references to the appropriate revision control branches and germinate output logs).
We will say who to talk to to decide whether to make a particular change/upload: that you should usually just go ahead and make change covered by own area of responsibility (which may be a package, or some cross-package property), and that for other things it's probably best to ask someone. We'll explain how to find out who last touched a package. The UDR will warn about what to do for changes that may cause compatibility problems or require corresponding changes to other packages.
In particular, we will say who is responsible for various important subsystems, including at least the following:
- kernel team, #ubuntu-kernel
- docs team, #ubuntu-docs
- universe packages, #ubuntu-motu
If you need advice, input or permission, the UDR will give you an idea of who to contact, or at least how to find out who to contact.
There will be information about freezes including who to contact about freeze exceptions, and reference will be made to BreezyReleaseSchedule (and successors).
We will describe what you should do after uploading, including where (if anywhere) to send copies of your patch, and what emails to expect and logs to check to see that all went well.
We will explain how to handle bugs, either by referring to the bug handling practices wiki page or preferably by incorporating the results of that UBZ BOF into the UDR.
There will be some documentation about how to get upload rights, including references to policy documents about registering GPG keys in launchpad, the differences between universe and main, and references to MOTU processes including wiki.ubuntu.com/REVU.
There will be a brief discussion about how we handle translations (in particular how we do it differently to Debian) and a reference to Rosetta and langpack documentation.
There will be some information about Ubuntu backports, including where to find them, some comments about how to be nice to backporters, and information about how to contact the backport team.
Information to be moved from elsewhere
Content should be transferred from DeveloperResources (which should become a navigation page), and the UDR will link to DeveloperResources.
The package introdeveloperdocs (currently awaiting review) contains some not entirely accurate content and should be abandoned/rejected. (Also, it has an incorrect version number for an Ubuntu-native package.)
Information about packaging and uploading
Several topics about the construction of packages need to be covered, including:
The differences in metadata between unmodified Debian source packages, Ubuntu-specific source packages, and Debian packages modified for Ubuntu.
The different approaches to packaging will be covered briefly, including specifically common approaches to constructing debian/rules, such as straightforward construction by-hand, debhelper, and cdbs; we will make some recommendations about when to use and when not to use these particular tools (eg, that most Gnome packages use cdbs).
Patch systems will also be described, and some advice given about whether to use one and which one to use. We will cover dpatch and cdbs at least, as well as reviewing manual approaches.
We will describe how to merge new versions from Debian, upstream or external repositories and discuss merge-o-matic.
There will be a brief discussion of the use of chroots and we'll also briefly mention other useful tools including pbuilder, sudo, lintian/linda and piuparts.
Implementation plan
We will focus on producing a useable UDR (by replacing Debian-specific information in the DDR) as soon as possible.
The resulting draft UDR will be made available to all Ubuntu developers as work proceeds on the additional Ubuntu-specific content.
Where new content is not Ubuntu-specific, we will supply it to the DDR maintainers via the usual Debian channels.
Arrangements will be made for the current versions of the UDR to be given a stable URL, and of course links will be made from appropriate places.
DeveloperDocumentation (last edited 2011-12-10 01:28:55 by static-50-53-26-176)