doc/webserver/developer-manual/git.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5   <title>The Git Repository</title>
   6   <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
   7   <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
   8   <link rel="PREVIOUS" title="Introduction" href="introduction.html">
   9   <link rel="NEXT" title="Documentation Guidelines" href="documentation.html">
  10   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  11   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  12 </head>
  13 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink="#840084" alink="#0000FF">
  14   <div class="NAVHEADER">
  15     <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
  16       <tr>
  17         <th colspan="3" align="center">Privoxy Developer Manual</th>
  18       </tr>
  19       <tr>
  20         <td width="10%" align="left" valign="bottom"><a href="introduction.html" accesskey="P">Prev</a></td>
  21         <td width="80%" align="center" valign="bottom"></td>
  22         <td width="10%" align="right" valign="bottom"><a href="documentation.html" accesskey="N">Next</a></td>
  23       </tr>
  24     </table>
  25     <hr align="left" width="100%">
  26   </div>
  27   <div class="SECT1">
  28     <h1 class="SECT1"><a name="GIT" id="GIT">2. The Git Repository</a></h1>
  29     <p>If you become part of the active development team, you will eventually need write access to our holy grail, the
  30     Git repository. One of the team members will need to set this up for you. Please read this chapter completely
  31     before accessing via Git.</p>
  32     <div class="SECT2">
  33       <h2 class="SECT2"><a name="GITACCESS" id="GITACCESS">2.1. Access to Git</a></h2>
  34       <p>The project's Git repository is hosted on the <a href="https://www.privoxy.org/" target="_top">Privoxy
  35       webserver</a>. For Privoxy team members with push privileges the Git repository URL is <tt class=
  36       "LITERAL">ssh://git@git.privoxy.org:23/git/privoxy.git</tt>.</p>
  37       <p>Contributors without push privileges can <span class="QUOTE">"git clone
  38       https://www.privoxy.org/git/privoxy.git"</span>.</p>
  39       <p>The central repository is called <tt class="LITERAL">privoxy</tt>, and the source branch is called <tt class=
  40       "LITERAL">master</tt>. Subfolders exist within the project for target-dependent build and packaging tools, each
  41       including the name of the target operating system in their name (e.g. Windows, OSXPackageBuilder, debian). There
  42       is a webview of the Git hierarchy at <a href="https://www.privoxy.org/gitweb/?p=privoxy.git;a=tree" target=
  43       "_top">https://www.privoxy.org/gitweb/?p=privoxy.git;a=tree</a>, which might help with visualizing how these
  44       pieces fit together.</p>
  45     </div>
  46     <div class="SECT2">
  47       <h2 class="SECT2"><a name="GITBRANCHES" id="GITBRANCHES">2.2. Branches</a></h2>
  48       <p>Whilst the central repository contains only the master branch, developers are of course free to create
  49       branches in their local repositories as they develop features, fixes, or update the target-dependent tools. Only
  50       once such changes are fully tested ought they be pushed back to the central repository master branch.</p>
  51       <p>Before pushing stuff, please rebase it on a current master so we get an uncomplicated commit history. Avoid
  52       merges where possible.</p>
  53       <p>Here's an example git sesssion that should result in a merge-free history:</p>
  54       <table border="0" bgcolor="#E0E0E0" width="100%">
  55         <tr>
  56           <td>
  57             <pre class="PROGRAMLISTING">fk@t520 ~/git/privoxy $git checkout master
  58 Switched to branch 'master'
  59 Your branch is up to date with 'origin/master'.
  60 # Make sure you have the latest changes
  61 fk@t520 ~/git/privoxy $git pull
  62 Already up to date.
  63 # Create a local banch for changes
  64 fk@t520 ~/git/privoxy $git checkout -b local-branch
  65 Switched to a new branch 'local-branch'
  66 # Create some change
  67 fk@t520 ~/git/privoxy $gmake dok dok-tidy
  68 [...]
  69 # Review your change
  70 fk@t520 ~/git/privoxy $git diff
  71 [...]
  72 # Commit your changes if they look goood
  73 fk@t520 ~/git/privoxy $git commit -m "developer-manual: Regenerate" doc/webserver/
  74 [local-branch 1abb7316] developer-manual: Regenerate
  75  1 file changed, 2 insertions(+), 2 deletions(-)
  76 # Review your commit
  77 fk@t520 ~/git/privoxy $git show
  78 [...]
  79 # Go to the master branch
  80 fk@t520 ~/git/privoxy $git checkout master
  81 Switched to branch 'master'
  82 Your branch is up to date with 'origin/master'.
  83 # Make sure you are still in sync
  84 fk@t520 ~/git/privoxy $git pull
  85 [...]
  86 Already up to date.
  87 # Apply the commit you made to the local-branch
  88 fk@t520 ~/git/privoxy $git cherry-pick local-branch
  89 [master 046e85e2] developer-manual: Regenerate
  90  Date: Tue Dec 15 05:10:07 2020 +0100
  91  1 file changed, 2 insertions(+), 2 deletions(-)
  92 # Make sure the history looks as expected
  93 fk@t520 ~/git/privoxy $git log -p
  94 # Finally push your change to the Privoxy repository
  95 fk@t520 ~/git/privoxy $git push
  96 [...]
  97 # Go back to the local branch
  98 fk@t520 ~/git/privoxy $git checkout local-branch
  99 # Rebase on top of master and continue hacking
 100 fk@t520 ~/git/privoxy $git rebase master
 101 Successfully rebased and updated refs/heads/local-branch.</pre>
 102           </td>
 103         </tr>
 104       </table>
 105       <p>At one time there were two distinct branches: stable and unstable. The more drastic changes were to be in the
 106       unstable branch. These branches have now been merged to minimize time and effort of maintaining two branches.</p>
 107     </div>
 108     <div class="SECT2">
 109       <h2 class="SECT2"><a name="GITCOMMIT" id="GITCOMMIT">2.3. Git Commit Guidelines</a></h2>
 110       <p>The source tree is the heart of every software project. Every effort must be made to ensure that it is
 111       readable, compilable and consistent at all times. We expect anyone with Git access to strictly adhere to the
 112       following guidelines:</p>
 113       <p>Basic Guidelines, for all branches:</p>
 114       <ul>
 115         <li>
 116           <p>Please don't commit even a small change without testing it thoroughly first. When we're close to a public
 117           release, ask a fellow developer to review your changes.</p>
 118         </li>
 119         <li>
 120           <p>Your commit message should give a concise overview of <span class="emphasis"><i class="EMPHASIS">what you
 121           changed</i></span> (no big details) and <span class="emphasis"><i class="EMPHASIS">why you changed
 122           it</i></span> Just check previous messages for good examples.</p>
 123         </li>
 124         <li>
 125           <p>Don't use the same message on multiple files, unless it equally applies to all those files.</p>
 126         </li>
 127         <li>
 128           <p>If your changes span multiple files, and the code won't recompile unless all changes are committed (e.g.
 129           when changing the signature of a function), then commit all files one after another, without long delays in
 130           between. If necessary, prepare the commit messages in advance.</p>
 131         </li>
 132         <li>
 133           <p>Before changing things on Git, make sure that your changes are in line with the team's general consensus
 134           on what should be done.</p>
 135         </li>
 136         <li>
 137           <p>Note that near a major public release, we get more cautious. There is always the possibility to submit a
 138           patch to the <a href="https://sourceforge.net/p/ijbswa/patches/" target="_top">patch tracker</a> or the
 139           <a href="https://lists.privoxy.org/mailman/listinfo/privoxy-devel" target="_top">privoxy-devel mailing
 140           list</a> instead.</p>
 141         </li>
 142       </ul>
 143     </div>
 144   </div>
 145   <div class="NAVFOOTER">
 146     <hr align="left" width="100%">
 147     <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
 148       <tr>
 149         <td width="33%" align="left" valign="top"><a href="introduction.html" accesskey="P">Prev</a></td>
 150         <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
 151         <td width="33%" align="right" valign="top"><a href="documentation.html" accesskey="N">Next</a></td>
 152       </tr>
 153       <tr>
 154         <td width="33%" align="left" valign="top">Introduction</td>
 155         <td width="34%" align="center" valign="top">&nbsp;</td>
 156         <td width="33%" align="right" valign="top">Documentation Guidelines</td>
 157       </tr>
 158     </table>
 159   </div>
 160 </body>
 161 </html>