DeveloperDocumentation
|
Size: 3427
Comment: wip
|
Size: 6772
Comment: add cats
|
| Deletions are marked like this. | Additions are marked like this. |
| 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 twisty maze of 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: |
| 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. fixme editing here | == Content == |
| Line 25: | Line 34: |
| * BreezyReleaseSchedule (don't copy content of this page, 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 |
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: |
| == BOF notes from Thursday == | 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: |
| say at top which ubuntu release the doc describes the processes for | === Specific topics and processes to cover === |
| Line 35: | Line 40: |
| how to build package - ubuntu-specific packages - ubuntu diffs from debian packages - syncs - package removals |
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 41: | Line 42: |
| 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 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: |
| wiki/DeveloperResources becomes link list and referred to in document | 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: |
| chroots | 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: |
| patch systems etc. | 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 62: | Line 53: |
| how to handle bugs (bug handling practices bof) |
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 65: | Line 55: |
| tools people might find helpful pbuilder sudo lintian / linda piuparts |
There will be information about freezes including who to contact about freeze exceptions, and reference will be made to BreezyReleaseSchedule (and successors). |
| Line 71: | Line 57: |
| Who is responsible for various important subsystems - kernel team, #ubuntu-kernel - docs team, #ubuntu-docs - universe packages, #ubuntu-motu ...? |
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 77: | Line 59: |
| How to merge new Debian or new Upstream or external Repositories merge-o-matic How to import from Debian |
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 82: | Line 61: |
| backports where to find them how to be nice to backporters who runs backports |
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 87: | Line 63: |
| When to not make changes - freezes how to get upload rights main vs universe (ref) motu 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. |
| Line 96: | Line 65: |
| get rid of introdeveloperdocs (at least, not have it in main) (also is Ubuntu-native with wrong version) |
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. |
| Line 100: | Line 67: |
| registering gpg key launchpad ? |
=== 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. CategoryDocumentation CategoryCleanup |
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 twisty maze of 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)