manpage-request

   1 Subject: request for manpage TOOL-dgit(7)
   2
   3 Severity: wishlist
   4
   5 Hi.  In this mail you'll find:
   6
   7  1. introduction
   8  2. description of dgit's model as it might concern TOOL
   9  3. suggested structure and for a new manpage
  10  4. some quirks and caveats
  11  5. references
  12
  13
  14 1. Introduction
  15
  16 You may have heard of dgit, which is a tool for sharing a canonical
  17 git representation of Debian packages, and particularly, packages in
  18 the Debian archive.
  19
  20 dgit is not a competitor to TOOL.  Indeed, dgit is intended to be
  21 complementary to existing Debian git packaging tools.  I think that
  22 TOOL can probably be used together with dgit, and it would be good to
  23 help users get TOOL and dgit to work well together.
  24
  25 It may also be that TOOL and/or dgit should get some new feature(s) or
  26 operation(s) to work better together.
  27
  28 Because I don't understand TOOL very well I'm not sure of the details.
  29 I'm hoping that you would like to write, or help me write, a manpage
  30 TOOL-dgit(7) (which I could cross-reference from dgit(1)).
  31
  32 Please let me know whether you think this is a good idea and whether
  33 you're able to help.
  34
  35
  36 2. dgit's purpose and model
  37
  38 dgit mainly replaces `sign and dupload', and `debcheckout'.  For each
  39 package there is a fast-forwarding git branch (one per suite) on a
  40 central dgit server.
  41
  42 The tree contents (in git terminology) of that branch correspond
  43 precisely to the contents of the corresponding source package.  (In
  44 more detail: dgit records a `patches-applied packaging branch without
  45 .pc directory'.)
  46
  47 The commit graph structure of the dgit branch is primarily up to the
  48 maintainer.  The only requirements imposed by dgit are that:
  49 successive uploads are fast forwards; and, that NMUs are represented
  50 by linear commit(s) on the tip of that branch.
  51
  52 When a maintainer is using dgit with TOOL, it is TOOL which determines
  53 the commit structure, subject to these constraints.
  54
  55
  56 3. Suggsted manpage skeleton
  57
  58 Here is a suggestion for what information is needed and how it might
  59 be structured.  Sorry that I don't have the knowledge to write
  60 something more complete.  (Below, XXX notes and comments in [ ] are
  61 directed to you, the maintainer of TOOL.)
  62
  63 If new TOOL or dgit need improvement, this ought to become obvious
  64 when trying to write the manpage.
  65
  66
  67 NAME
  68     TOOL-dgit(7) - use of dgit with TOOL
  69
  70 SYNOPSIS
  71
  72     dgit can be used to publish and share the git history that TOOL
  73     works with.  This dgit integration guide is for the TOOL-using
  74     maintainer.
  75
  76 PUSHING (UPLOADING) WITH DGIT
  77
  78     TOOL's XXX [which branch?] branch is directly suitable for use
  79     with dgit push.
  80
  81     After finalising development with
  82        TOOL MAKE-THE-RIGHT-THING-TO-UPLOAD
  83     the binary and source package(s) should be built with
  84        dgit sbuild
  85     or
  86        dgit build
  87
  88     Then dgit push can be used.  See dgit(1) for details.
  89
  90 USING *TOOL* WITH DGIT FOR THE FIRST TIME
  91
  92     dgit requires that each upload is a fast forward from the previous
  93     one (even if the dgit view of the previous upload is a commit
  94     synthesised by dgit).
  95
  96     So when switching to using TOOL with dgit, it is necessary to
  97     stitch the previous dgit history into the git branch:
  98
  99     1. Run dgit fetch (or dgit fetch <suite>) to get the dgit view
 100        of the current archive state.
 101
 102     2. Check (for example by looking at debian/changelog in your own
 103        branch, and comparing it to debian/changelog in dgit/sid) that
 104        the version you are about to upload really is descended from
 105        the last upload.
 106
 107     3. Run
 108          git merge -s ours dgit/sid
 109        to generate a `merge' commit which contains exactly your code
 110        but which is also a descendant of the dgit history.
 111
 112     When you next come to run TOOL you will need to XXX [will TOOL
 113     work on such history or does user need to do something special?]
 114
 115 HANDLING AN NMU
 116
 117     An NMU should appear in the git history as some additional,
 118     linear, commits, descended from the commit of your last upload.
 119
 120     To integrate these changes into your own XXX [ git history,
 121     branch, whatever? ] you must XXX [ do what? ]
 122
 123     NMUs made with dgit will contain whatever git history the NMUer
 124     pushed, which should be reasonably clean.  (If not, complain to
 125     the NMUer.)
 126
 127 SEE ALSO
 128     dgit(1), dgit(7), ...
 129
 130     NMUers who
 131
 132
 133 4. Quirks
 134
 135     The dgit view of an NMU may contain commits withh a mixture of
 136     debian/ and upstream changes.  The intermediate states in the dgit
 137     git branch, between the last maintainer upload and the nmu, may
 138     not necessarily have the corresponding updates to
 139     debian/patches.
 140
 141     NMUs not made with dgit will appear as a merge of 1. a root commit
 142     describing the .dsc that was uploaded, and 2. a merge to stitch it
 143     into the suite branch.
 144
 145     dgit's source packages and git trees contain .gitignore.  Current
 146     default behaviour for dpkg-buildpackage -I is to remove
 147     .gitignore.  This is not correct for dgit because the .dsc and git
 148     tree must be identical.  The main effect is just that it is best
 149     to use of dgit's build wrapper operations to build the package,
 150     since dgit knows the right -I options.
 151
 152
 153 5. References
 154
 155  dgit(1) manpage
 156  http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.1
 157
 158  dgit(7) manpage
 159  http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.1
 160
 161  dgit 1.0 release announcement
 162  https://lists.debian.org/debian-devel-announce/2015/07/msg00003.html
 163