X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=5768b30aec3b8a776f9d73c0357c3cf2b3439eed;hp=f25a2800cbe303711dcba8392de0295850fc443a;hb=1145364666f6eea05293de6332a0e17789748348;hpb=d718332b42f884d9c3c2fd0cfa9b83f4973c6971 diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index f25a2800..5768b30a 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -192,6 +192,56 @@ Hal. Before pushing stuff, please rebase it on a current master so we get an uncomplicated commit history. Avoid merges where possible. + + Here's an example git sesssion that should result in a merge-free history: + + +fk@t520 ~/git/privoxy $git checkout master +Switched to branch 'master' +Your branch is up to date with 'origin/master'. +# Make sure you have the latest changes +fk@t520 ~/git/privoxy $git pull +Already up to date. +# Create a local banch for changes +fk@t520 ~/git/privoxy $git checkout -b local-branch +Switched to a new branch 'local-branch' +# Create some change +fk@t520 ~/git/privoxy $gmake dok dok-tidy +[...] +# Review your change +fk@t520 ~/git/privoxy $git diff +[...] +# Commit your changes if they look goood +fk@t520 ~/git/privoxy $git commit -m "developer-manual: Regenerate" doc/webserver/ +[local-branch 1abb7316] developer-manual: Regenerate + 1 file changed, 2 insertions(+), 2 deletions(-) +# Review your commit +fk@t520 ~/git/privoxy $git show +[...] +# Go to the master branch +fk@t520 ~/git/privoxy $git checkout master +Switched to branch 'master' +Your branch is up to date with 'origin/master'. +# Make sure you are still in sync +fk@t520 ~/git/privoxy $git pull +[...] +Already up to date. +# Apply the commit you made to the local-branch +fk@t520 ~/git/privoxy $git cherry-pick local-branch +[master 046e85e2] developer-manual: Regenerate + Date: Tue Dec 15 05:10:07 2020 +0100 + 1 file changed, 2 insertions(+), 2 deletions(-) +# Make sure the history looks as expected +fk@t520 ~/git/privoxy $git log -p +# Finally push your change to the Privoxy repository +fk@t520 ~/git/privoxy $git push +[...] +# Go back to the local branch +fk@t520 ~/git/privoxy $git checkout local-branch +# Rebase on top of master and continue hacking +fk@t520 ~/git/privoxy $git rebase master +Successfully rebased and updated refs/heads/local-branch. + @@ -2216,7 +2295,7 @@ for-privoxy-version=3.0.11 $ git tag # to see the tags - $ git log [last release tag]..HEAD > /tmp/log + $ git log [last release tag]..master > /tmp/log # get the commit log since the last release $ utils/makeChangeLog /tmp/log > /tmp/change.log # reformat the commit log @@ -2287,14 +2366,14 @@ for-privoxy-version=3.0.11 link from the main page since we need to keep manuals for various versions available). The CGI pages will link to something like https://www.privoxy.org/$(VERSION)/user-manual/. This - will need to be updated for each new release. There is no Makefile - target for this at this time!!! It needs to be done manually. + needs to be updated for each new release and is done with the + webserver target. Tag all files in Git with the version number with - git tag v_X_Y_Z. + git tag -s v_X_Y_Z. Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc. @@ -2411,9 +2490,7 @@ for-privoxy-version=3.0.11 Also suggested: Developer Manual (doc/webserver/developer-manual) and ChangeLog (top-level directory). FAQ and the manuals are - HTML docs. There are also text versions in - doc/text/ which could conceivably also be - included. + HTML docs. The documentation has been designed such that the manuals are linked @@ -2443,7 +2520,8 @@ for-privoxy-version=3.0.11 - Other configuration files (default.action and + Other configuration files (default.action, + regression-tests.action and default.filter) should be installed as the new defaults, but all previously installed configuration files should be preserved as backups. This is just good manners :-) These files are @@ -2478,10 +2556,9 @@ for-privoxy-version=3.0.11 First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing - packages" above). Then run: + packages" above). Then run from that directory: - cd current autoheader && autoconf && ./configure @@ -2490,98 +2567,6 @@ for-privoxy-version=3.0.11 make tarball-dist - - To upload the package to Sourceforge, simply issue - - - make tarball-upload - - - Go to the displayed URL and release the file publicly on Sourceforge. - For the change log field, use the relevant section of the - ChangeLog file. - - - - SuSE, Conectiva or Red Hat RPM - - In following text, replace dist - with either rh for Red Hat or suse for SuSE. - - - First, make sure that you have freshly exported the right - version into an empty directory. (See "Building and releasing - packages" above). - - - As the only exception to not changing anything after export from Git, - now examine the file privoxy-dist.spec - and make sure that the version information and the RPM release number are - correct. The RPM release numbers for each version start at one. Hence it must - be reset to one if this is the first RPM for - dist which is built from version - X.Y.Z. Check the - file - list if unsure. Else, it must be set to the highest already available RPM - release number for that version plus one. - - - Then run: - - - cd current - autoheader && autoconf && ./configure - - - Then do - - - make dist-dist - - - To upload the package to Sourceforge, simply issue - - - make dist-upload rpm_packagerev - - - where rpm_packagerev is the - RPM release number as determined above. - Go to the displayed URL and release the file publicly on Sourceforge. - Use the release notes and change log from the source tarball package. - - - - Solaris - - Login to Sourceforge's compilefarm via ssh: - - - ssh cf.sourceforge.net - - - Choose the right operating system (not the Debian one). - When logged in, make sure that you have freshly exported the right - version into an empty directory. (See "Building and releasing - packages" above). Then run: - - - cd current - autoheader && autoconf && ./configure - - - Then run - - - gmake solaris-dist - - - which creates a gzip'ed tar archive. Sadly, you cannot use make - solaris-upload on the Sourceforge machine (no ncftpput). You now have - to manually upload the archive to Sourceforge's ftp server and release - the file publicly. Use the release notes and Change Log from the - source tarball package. - Windows @@ -2652,12 +2637,8 @@ for-privoxy-version=3.0.11 This will create ../privoxy_&p-version;-&p-status;-1_i386.deb - which can be uploaded. To upload the package to Sourceforge, simply - issue + which can be uploaded. - - make debian-upload - Mac OS X @@ -2772,38 +2753,10 @@ for-privoxy-version=3.0.11 Uploading and Releasing Your Package After the package is ready, it is time to upload it - to SourceForge, and go through the release steps. The upload - is done via FTP: - - - - - Upload to: ftp://upload.sourceforge.net/incoming - - - - - user: anonymous - - - - - password: ijbswa-developers@lists.sourceforge.net - - - - - Or use the make targets as described above. - - - Once this done go to - - https://sourceforge.net/project/admin/editpackages.php?group_id=11118, - making sure you are logged in. Find your target platform in the - second column, and click Add Release. You will - then need to create a new release for your package, using the format - of $VERSION ($CODE_STATUS), e.g. &p-version; - (beta). + and go through the release steps. The upload + is done at + SourceForge + after logging in. Now just follow the prompts. Be sure to add any appropriate Release @@ -2830,7 +2783,7 @@ for-privoxy-version=3.0.11 When all (or: most of the) packages have been uploaded and made available, send an email to the announce mailing - list, Subject: "Version X.Y.Z available for download". Be sure to + list, Subject: "Announcing Privoxy X.Y.Z $CODE_STATUS". Be sure to include the download location, the release notes and the Changelog. Also, post an