doc/webserver/developer-manual/git.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >The Git Repository</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
   9 REL="HOME"
  10 TITLE="Privoxy Developer Manual"
  11 HREF="index.html"><LINK
  12 REL="PREVIOUS"
  13 TITLE="Introduction"
  14 HREF="introduction.html"><LINK
  15 REL="NEXT"
  16 TITLE="Documentation Guidelines"
  17 HREF="documentation.html"><LINK
  18 REL="STYLESHEET"
  19 TYPE="text/css"
  20 HREF="../p_doc.css"><META
  21 HTTP-EQUIV="Content-Type"
  22 CONTENT="text/html;
  23 charset=ISO-8859-1"></HEAD
  24 ><BODY
  25 CLASS="SECT1"
  26 BGCOLOR="#EEEEEE"
  27 TEXT="#000000"
  28 LINK="#0000FF"
  29 VLINK="#840084"
  30 ALINK="#0000FF"
  31 ><DIV
  32 CLASS="NAVHEADER"
  33 ><TABLE
  34 SUMMARY="Header navigation table"
  35 WIDTH="100%"
  36 BORDER="0"
  37 CELLPADDING="0"
  38 CELLSPACING="0"
  39 ><TR
  40 ><TH
  41 COLSPAN="3"
  42 ALIGN="center"
  43 >Privoxy Developer Manual</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="bottom"
  50 ><A
  51 HREF="introduction.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="80%"
  57 ALIGN="center"
  58 VALIGN="bottom"
  59 ></TD
  60 ><TD
  61 WIDTH="10%"
  62 ALIGN="right"
  63 VALIGN="bottom"
  64 ><A
  65 HREF="documentation.html"
  66 ACCESSKEY="N"
  67 >Next</A
  68 ></TD
  69 ></TR
  70 ></TABLE
  71 ><HR
  72 ALIGN="LEFT"
  73 WIDTH="100%"></DIV
  74 ><DIV
  75 CLASS="SECT1"
  76 ><H1
  77 CLASS="SECT1"
  78 ><A
  79 NAME="GIT"
  80 >2. The Git Repository</A
  81 ></H1
  82 ><P
  83 >      If you become part of the active development team, you will eventually
  84       need write access to our holy grail, the Git repository. One of the
  85       team members will need to set this up for you. Please read
  86       this chapter completely before accessing via Git.
  87     </P
  88 ><DIV
  89 CLASS="SECT2"
  90 ><H2
  91 CLASS="SECT2"
  92 ><A
  93 NAME="GITACCESS"
  94 >2.1. Access to Git</A
  95 ></H2
  96 ><P
  97 >        The project's Git repository is hosted on the
  98         <A
  99 HREF="https://www.privoxy.org/"
 100 TARGET="_top"
 101 >Privoxy webserver</A
 102 >.
 103         For Privoxy team members with push privileges the Git repository URL is
 104         <TT
 105 CLASS="LITERAL"
 106 >ssh://git@git.privoxy.org:23/git/privoxy.git</TT
 107 >.
 108       </P
 109 ><P
 110 >       Contributors without push privileges can
 111        <SPAN
 112 CLASS="QUOTE"
 113 >"git clone https://www.privoxy.org/git/privoxy.git"</SPAN
 114 >.
 115       </P
 116 ><P
 117 >        The central repository is called <TT
 118 CLASS="LITERAL"
 119 >privoxy</TT
 120 >, and the
 121         source branch is called <TT
 122 CLASS="LITERAL"
 123 >master</TT
 124 >. Subfolders exist
 125         within the project for target-dependent build and  packaging tools, each
 126         including the name of the target operating system in their name (e.g.
 127         Windows, OSXPackageBuilder, debian). There is a webview of the Git
 128         hierarchy at
 129         <A
 130 HREF="https://www.privoxy.org/gitweb/?p=privoxy.git;a=tree"
 131 TARGET="_top"
 132 >                    https://www.privoxy.org/gitweb/?p=privoxy.git;a=tree</A
 133 >,
 134         which might help with visualizing how these pieces fit together.
 135       </P
 136 ></DIV
 137 ><DIV
 138 CLASS="SECT2"
 139 ><H2
 140 CLASS="SECT2"
 141 ><A
 142 NAME="GITBRANCHES"
 143 >2.2. Branches</A
 144 ></H2
 145 ><P
 146 >       Whilst the central repository contains only the master branch, developers
 147        are of course free to create branches in their local repositories as they
 148        develop features, fixes, or update the target-dependent tools. Only once
 149        such changes are fully tested ought they be pushed back to the central
 150        repository master branch.
 151      </P
 152 ><P
 153 >       Before pushing stuff, please rebase it on a current master so we get
 154        an uncomplicated commit history. Avoid merges where possible.
 155      </P
 156 ><P
 157 >       Here's an example git sesssion that should result in a merge-free history:
 158      </P
 159 ><TABLE
 160 BORDER="0"
 161 BGCOLOR="#E0E0E0"
 162 WIDTH="100%"
 163 ><TR
 164 ><TD
 165 ><PRE
 166 CLASS="PROGRAMLISTING"
 167 >  fk@t520 ~/git/privoxy $git checkout master
 168   Switched to branch 'master'
 169   Your branch is up to date with 'origin/master'.
 170   # Make sure you have the latest changes
 171   fk@t520 ~/git/privoxy $git pull
 172   Already up to date.
 173   # Create a local banch for changes
 174   fk@t520 ~/git/privoxy $git checkout -b local-branch
 175   Switched to a new branch 'local-branch'
 176   # Create some change
 177   fk@t520 ~/git/privoxy $gmake dok dok-tidy
 178   [...]
 179   # Review your change
 180   fk@t520 ~/git/privoxy $git diff
 181   [...]
 182   # Commit your changes if they look goood
 183   fk@t520 ~/git/privoxy $git commit -m "developer-manual: Regenerate" doc/webserver/
 184   [local-branch 1abb7316] developer-manual: Regenerate
 185    1 file changed, 2 insertions(+), 2 deletions(-)
 186   # Review your commit
 187   fk@t520 ~/git/privoxy $git show
 188   [...]
 189   # Go to the master branch
 190   fk@t520 ~/git/privoxy $git checkout master
 191   Switched to branch 'master'
 192   Your branch is up to date with 'origin/master'.
 193   # Make sure you are still in sync
 194   fk@t520 ~/git/privoxy $git pull
 195   [...]
 196   Already up to date.
 197   # Apply the commit you made to the local-branch
 198   fk@t520 ~/git/privoxy $git cherry-pick local-branch
 199   [master 046e85e2] developer-manual: Regenerate
 200    Date: Tue Dec 15 05:10:07 2020 +0100
 201    1 file changed, 2 insertions(+), 2 deletions(-)
 202   # Make sure the history looks as expected
 203   fk@t520 ~/git/privoxy $git log -p
 204   # Finally push your change to the Privoxy repository
 205   fk@t520 ~/git/privoxy $git push
 206   [...]
 207   # Go back to the local branch
 208   fk@t520 ~/git/privoxy $git checkout local-branch
 209   # Rebase on top of master and continue hacking
 210   fk@t520 ~/git/privoxy $git rebase master
 211   Successfully rebased and updated refs/heads/local-branch.</PRE
 212 ></TD
 213 ></TR
 214 ></TABLE
 215 ><P
 216 >      At one time there were two distinct branches: stable and unstable. The
 217       more drastic changes were to be in the unstable branch. These branches
 218       have now been merged to minimize time and effort of maintaining two
 219       branches.
 220      </P
 221 ></DIV
 222 ><DIV
 223 CLASS="SECT2"
 224 ><H2
 225 CLASS="SECT2"
 226 ><A
 227 NAME="GITCOMMIT"
 228 >2.3. Git Commit Guidelines</A
 229 ></H2
 230 ><P
 231 >        The source tree is the heart of every software project. Every effort must
 232         be made to ensure that it is readable, compilable and consistent at all
 233         times.  We expect anyone with Git access to strictly
 234         adhere to the following guidelines:
 235       </P
 236 ><P
 237 >       Basic Guidelines, for all branches:
 238       </P
 239 ><P
 240 ></P
 241 ><UL
 242 ><LI
 243 ><P
 244 >            Please don't commit even
 245             a small change without testing it thoroughly first. When we're
 246             close to a public release, ask a fellow developer to review your
 247             changes.
 248           </P
 249 ></LI
 250 ><LI
 251 ><P
 252 >            Your commit message should give a concise overview of <SPAN
 253 CLASS="emphasis"
 254 ><I
 255 CLASS="EMPHASIS"
 256 >what you
 257             changed</I
 258 ></SPAN
 259 > (no big details) and <SPAN
 260 CLASS="emphasis"
 261 ><I
 262 CLASS="EMPHASIS"
 263 >why you changed it</I
 264 ></SPAN
 265 >
 266             Just check previous messages for good examples.
 267           </P
 268 ></LI
 269 ><LI
 270 ><P
 271 >            Don't use the same message on multiple files, unless it equally applies to
 272             all those files.
 273           </P
 274 ></LI
 275 ><LI
 276 ><P
 277 >            If your changes span multiple files, and the code won't recompile unless
 278             all changes are committed (e.g. when changing the signature of a function),
 279             then commit all files one after another, without long delays in between.
 280             If necessary, prepare the commit messages in advance.
 281           </P
 282 ></LI
 283 ><LI
 284 ><P
 285 >            Before changing things on Git, make sure that your changes are in line
 286             with the team's general consensus on what should be done.
 287           </P
 288 ></LI
 289 ><LI
 290 ><P
 291 >            Note that near a major public release, we get more cautious.
 292             There is always the possibility to submit a patch to the <A
 293 HREF="https://sourceforge.net/p/ijbswa/patches/"
 294 TARGET="_top"
 295 >patch
 296             tracker</A
 297 > or the <A
 298 HREF="https://lists.privoxy.org/mailman/listinfo/privoxy-devel"
 299 TARGET="_top"
 300 >privoxy-devel mailing list</A
 301 >
 302             instead.
 303           </P
 304 ></LI
 305 ></UL
 306 ></DIV
 307 ></DIV
 308 ><DIV
 309 CLASS="NAVFOOTER"
 310 ><HR
 311 ALIGN="LEFT"
 312 WIDTH="100%"><TABLE
 313 SUMMARY="Footer navigation table"
 314 WIDTH="100%"
 315 BORDER="0"
 316 CELLPADDING="0"
 317 CELLSPACING="0"
 318 ><TR
 319 ><TD
 320 WIDTH="33%"
 321 ALIGN="left"
 322 VALIGN="top"
 323 ><A
 324 HREF="introduction.html"
 325 ACCESSKEY="P"
 326 >Prev</A
 327 ></TD
 328 ><TD
 329 WIDTH="34%"
 330 ALIGN="center"
 331 VALIGN="top"
 332 ><A
 333 HREF="index.html"
 334 ACCESSKEY="H"
 335 >Home</A
 336 ></TD
 337 ><TD
 338 WIDTH="33%"
 339 ALIGN="right"
 340 VALIGN="top"
 341 ><A
 342 HREF="documentation.html"
 343 ACCESSKEY="N"
 344 >Next</A
 345 ></TD
 346 ></TR
 347 ><TR
 348 ><TD
 349 WIDTH="33%"
 350 ALIGN="left"
 351 VALIGN="top"
 352 >Introduction</TD
 353 ><TD
 354 WIDTH="34%"
 355 ALIGN="center"
 356 VALIGN="top"
 357 >&nbsp;</TD
 358 ><TD
 359 WIDTH="33%"
 360 ALIGN="right"
 361 VALIGN="top"
 362 >Documentation Guidelines</TD
 363 ></TR
 364 ></TABLE
 365 ></DIV
 366 ></BODY
 367 ></HTML
 368 >