SomeReviewNotes

Revision 5 as of 2007-06-12 13:31:17

Clear message

Introduction

  • This page contains a summary of my thoughts towards ["MOTU/WikiCleanUp"], driven in part by a review of the Wiki.

General Notes

Audience

  • Documententation should be written so as to provide clear information to four distinct groups:
  • Those who will need a sponsor to accomplish the goal
  • Those who will perform the action directly
  • Those sponsoring/reviewing the actions of others

Integration with Launchpad

  • Where practicable, any guide towards doing things to support development should include documentation of the workflow using launchpad to complete the action.

Processes

  • Each process page should contain the following sections:
  • Description of the purpose of the process
  • The relevant policy governing the process
  • Procedural documentation for each distinct audience Process pages should be based on a Task focus, rather than

Organisisation

  • All Development-related pages should be in a clear Development namespace
  • There should be no pages that are only links to other pages - use a TOC instead
  • There should be clear separation between information about Ubuntu-specific activities and general information. Where appropriate, process pages should link to general guides, and general guides should link to relevant Ubuntu processes.
  • There should be overview pages for each development role (Contributor, Developer, Core Developer) pointing to relevant process pages, and other links of interest.

  • This section needs more thought Smile :)

Page Size

  • Small pages should be avoided, and the content rather included in a larger page, to provide the appropriate context for the reader.

Review of pages in the Wiki

  • The sections below are loosely organised as I thought of categories: they don't really mean anything other than being a way for me to organise my thoughts. This is also currently a work in progress. While I've read all the pages, I've not yet compiled all the comments.

Contributing

  • ["ContributeToUbuntu"] is a good page, but the section on contributing to Universe needs an update.

  • ["HelpingUbuntu"] is nice, and has lots of content that probably belongs in ["ContributeToUbuntu"]

  • ["EasyWaysToHelpUbuntu"] Needs cleanup, and might be better as a section in ["ContributeToUbuntu"]

  • ["MOTU/Contributing"] is over-detailed, and doesn't match the other contributing documents well. Also, there are instructions here that are useful beyond contributing (How to prepare a patch, how to prepare a new revision, how to prepare a new package).

  • ["ContributingToDebian"] could use a refresh, and update, and pointers to DCT

  • ["NewDevelopersAndMaintainers"] is confusingly named. If this must be kept for historical reasons, it should be put in /Historical/ or /Archive/. External links that break reaching this page are probably preferable to actually presenting this content as official.

  • ["MOTU/Hopeful/Tips"] has a name that implies something other than "THIS PAGE IS MOSTLY REDUNDANT WITH OTHER PAGES ON THE WIKI.".

  • ["DocumentationTeam/GettingStarted"] is a nice example of an introduction. Let's shoot for something with this feel.

Packaging

  • ["HowToBuildDebianPackagesFromScratch"] needs some work (and should offer alternatives to dh_make)

  • ["MOTU/School/PackagingBasics"] needs an update, and the extraction of documentation, rather than a School session
  • ["MOTU/School/2005-12-10"] could use a better title, and some cleanup
  • ["MOTU/Packages/Reviewing"] looks good, but could use a cleanup / refresh
  • ["MOTU/Packages/Reviewing/Tips"] would be better to merge up. More generally, those reviewed should be exposed to the reviewers guide so that they may pre-review, if so desired.
  • ["MOTU/Packages/Packaging/Kubuntu"] seems to be a parallel document. There is useful information here, but overall management would be easier with everything in one place

  • ["UbuntuPackagingChanges"] needs to be up-to-date, and be easier to find. I never encountered this previously.

  • ["MOTU/Packages/Packaging/Tips"] has some useful content, but it's uneven, and not very friendly to read

  • ["MOTU/Packages/CommonPackagingMistakes/DebianCopyright"] is nice, but would benefit from review & a TOC

  • ["MOTU/Packages/CommonPackagingMistakes/ChangingTheOrigTarball"] is nice, but would benefit from a review & a TOC

  • ["MOTU/School/PackagingMistakes"] should mined for more like the above, and all should be named something less negative in the final version.

Patching

  • ["MeetingLogs/openweekfeisty/patching"] could use review, and extraction of good bits not covered elsewhere.
  • ["MOTU/School/PatchingSources"] needs a TOC, and likely a bit more dicussion
  • ["Bugs/HowToFix"] would benefit from review and better process integration (what is sought from those who can edit code, but are unfamilar with packaging?)

General

  • ["UbuntuDevelopment"] should be overhauled as part of the cleanup.

  • ["PackageManagement"] is very outdated, but has some useful bits. It probably needs pointers to a real spec

  • Pages like ["MozillaTeam/Bugs/Triage/Responses"] should be encouraged for all teams.
  • ["MOTU/Documentation/Todo"] appears to be the last attempt - why branch?

Processes

  • ["SeedManagement"] is nice, but it needs a cleanup for 1) TOC, and 2) reorg so that the information at the top of the page is more accessible to those unfamiliar with seeds.

  • ["MOTU/Packages/Merging"] covers the topic well (could use a TOC), but would benefit from launchpad notes, and encouragement to include outstanding Ubuntu bugfixes at the same time as the merge (several Contributors have expressed that they would patch bug X as soon as package Y was merged, whereas I think both should be the same upload to reduce archive churn and the load on the buildds).
  • ["MOTU/Merging"] contains lots of useful links. More generally, there should be one page for all merging, to all repositories, with variance specified where appropriate (it's not that different).

  • ["StableReleaseUpdates"] would benefit from a rewrite and rationalisation to cover the procedures for both main/restricted and universe/multiverse.

  • ["MOTU/SRU"] should be fed into StableReleaseUpdates

  • ["SecurityUpdateProcedures"] needs a cleanup to make it easier to understand

  • ["MOTU/Launchpad/Guide"] is outdated, and in some cases wrong, but may contain useful guidelines on launchpad interaction which are not documented elsewhere
  • ["MOTU/Packages/REVU"] should probably be split, such that much of the content becomes a manual that is specific to the REVU tool, and the remainder feeds back into more general processes for 1) getting new software into Ubutu, and 2) releasing new upstream versions into Ubuntu prior to inclusion in Debian.

  • ["DebianMaintainerField"] is a spec, but there should be a maintainermangling process as a result.

  • ["MOTU/Sponsorship/SponsorsQueue"] is useful, but I wonder if Sponsorship is actually a separate process...

  • ["SponsorshipProcess"] would benefit from cleanup, audience expansion, generalisation, and a TOC

  • ["UbuntuMainInclusionRequirements"] is nice, but could use a TOC and audience expansion

Bugs

  • ["Bugs/UsefulSearches"] seems like the best place to keep lots of searches. Those MOTU pages with bug searches might do better to be added as part of a rewrite of this page.

  • ["DrinkingFromTheFirehose"] is nice, but I haven't seen much documentation as to the resulting new processes. Is this bughelper? Does it just need more work?

  • ["MOTU/Bugs"] - a lot of this seems like it might be better to feed into Bugs/, and point there, rather than keeping it separate. The remainder seems process-based, and would be better there.
  • ["Bugs/ReportingToDebian"] should be emphasized: it's especially important to encourage those making new revisions, or processing merges to check to make sure the bugs are filed in Debian, and if so, are linked appropriately to the (now closed) LP bugs. Some cleanup would be nice as well, and perhaps less emphasis on reportbug, for those with broken local mail configurations.

Other

  • ["MOTU/Packages/DesktopFiles"] could use a TOC, and perhaps a rewrite

  • ["LaunchpadHowTo"] Could use signifcant expansion, including notes on things for which one must belong to specific teams, etc.

  • ["MOTU/School"] should be more about school (and planning sessions, archives, etc.) and less about MOTU and contributing
  • ["MOTU/School/Requests"] needs a kick to be useful again - I don't hear enough about it
  • ["MOTUNotes"] probably belongs in another place, but this requires coordination with upstream. Also, it's hopelessly out of date.
  • ["MOTU/TODO"] is a great list of resources, and a handy way to track things, and should have a place somewhere. It could also be prettified. Some of the philosophy expressed in ["MOTU/Contributing"] might be useful here. Use of real URLs is also preferred, as it makes it easier to tweak.

Tools

  • ["PbuilderHowto"] could use a refresh (or rewrite to use terms like "current development release", "current stable release", "current LTS release", etc.). Also, aren't there some scripts that do most of this now?

  • ["MultiDistroTools"] could use a refresh, an upstream, and maybe even a distributed package

  • ["MOTU/Packages/REVU/REVU-Tools"] should be stuck in the archives and referenced in the Reviewing guide

Specs

  • ["CodeReviewSLA"] should probably be reconcilied with REVU2 towards developing a workflow that is easy for everyone - we should base tools on workflow, not workflow on tools (especially when the tools don't yet exist)

  • ["DeveloperDocumentation"] should make the status as a Spec clearer.

  • ["AutomakeTransition"] should be more clearly highlighted. There's no reason this couldn't be advanced as part of merging (especially if patches flow back to the Debian BTS).

  • ["MotuProcessesSpec"] is a good spec, but these processes should be more clearly documented outside the spec to allow for changes over time.

  • ["EfficientCodingStrategySpec"] doesn7t seem very lively, but information produced as a result would do well to be documented in the Development tree, so that people look for that when making adjustments.

Teams

  • Generally, how is a MOTU team different from other Development teams?
  • ["MOTU/Teams/Audio"] seems to have moved into Ubuntu Studio. or more generally into the Audio team (depending on which portion is considered)
  • ["MOTU"] needs signfiicant overhaul as part of the cleanup

  • ["UbuntuDevelopers"] is a good structure, but doesn't appear in line with current MOTU thinking. Also, as a team page, it should be more ... something.

  • ["MOTU/Teams/Howto"] Doesn't seem meaningfully specialised for MOTU - content should be fed to ["BuildingCommunity/CreatingTeamGuide"]