On 18/08/2015 20:24, Paul Jakma wrote:
> MarkDown seems to be the thing these days, and easier on the eyes than
> LaTeX. Pandoc can still render it to PDF via TeX anyway.
just a nit, but does this markdown variant require that ascii single-quotes
be replaced by unicode open- and close- single quotes?
Otherwise ++1.
Nick
> Note, if not obvious, this applies after git mv to rename the .tex to .md -
> commit not shown.
>
> * HACKING: Converted initially from LaTeX to markdown with:
>
> 'pandoc -f latex -t markdown HACKING.tex'
>
> Then tweaked by hand to add a header with some suitable variables for
> the
> pandoc LaTeX template to make better use of the page space, and to add
> newpages so the title page is standalone as in the previous version.
>
> Also went through and reflowed paragraphs best as I could to make them
> match the previous document, to make it a little easier to verify
> nothing
> had been changed other than the markup, via diff.
>
> PDF can be generated with: 'pandoc -o HACKING.pdf HACKING.md'
>
> diff --git a/HACKING.md b/HACKING.md
> index be86ae1..3a449da 100644
> --- a/HACKING.md
> +++ b/HACKING.md
> @@ -1,30 +1,26 @@
> -%% -*- mode: text; -*-
> -%% $QuaggaId: Format:%an, %ai, %h$ $
> -
> -\documentclass[oneside]{article}
> -\usepackage{parskip}
> -\usepackage[bookmarks,colorlinks=true]{hyperref}
> -
> -\title{Conventions for working on Quagga}
> -
> -\begin{document}
> -\maketitle
> -
> -This is a living document. Suggestions for updates, via the
> -\href{http://lists.quagga.net/mailman/listinfo/quagga-dev}{quagga-dev list},
> -are welcome.
> -
> -\tableofcontents
> +---
> +title: Conventions for working on Quagga +papersize: a4paper
> +geometry: scale=0.82
> +fontsize: 11pt
> +toc: true
> +date: \today
> +include-before: + \large This is a living document. Suggestions for
> updates, via the
> + [quagga-dev list](http://lists.quagga.net/mailman/listinfo/quagga-dev),
> + are welcome. \newpage
> +...
>
> -\section{GUIDELINES FOR HACKING ON QUAGGA}
> -\label{sec:guidelines}
> +\newpage
>
> +GUIDELINES FOR HACKING ON QUAGGA {#sec:guidelines}
> +================================
>
> GNU coding standards apply. Indentation follows the result of
> -invoking GNU indent (as of 2.2.8a) with the --nut argument.
> +invoking GNU indent (as of 2.2.8a) with the -–nut argument.
>
> Originally, tabs were used instead of spaces, with tabs are every 8
> columns. -However, tab's interoperability issues mean space characters are
> now preferred for
> +However, tab’s interoperability issues mean space characters are now
> preferred for
> new changes. We generally only clean up whitespace when code is
> unmaintainable
> due to whitespace issues, to minimise merging conflicts.
>
> @@ -38,14 +34,14 @@ consequences.
>
> Each file in the Git repository should have a git format-placeholder (like
> an RCS Id keyword), somewhere very near the top, commented out appropriately
> -for the file type. The placeholder used for Quagga (replacing <dollar> with
> -\$) is:
> +for the file type. The placeholder used for Quagga (replacing \<dollar\>
> +with \$) is:
>
> - \verb|$QuaggaId: <dollar>Format:%an, %ai, %h<dollar> $|
> +`$QuaggaId: <dollar>Format:%an, %ai, %h<dollar> $`
>
> See line 2 of HACKING.tex, the source for this document, for an example.
>
> -This placeholder string will be expanded out by the `git archive' commands,
> +This placeholder string will be expanded out by the ‘git archive’ commands,
> which is used to generate the tar archives for snapshots and releases.
>
> Please document fully the proper use of a new function in the header file
> @@ -53,10 +49,9 @@ in which it is declared. And please consult existing
> headers for
> documentation on how to use existing functions. In particular, please
> consult
> these header files:
>
> -\begin{description}
> - \item{lib/log.h} logging levels and usage guidance
> - \item{[more to be added]}
> -\end{description}
> +<span>lib/log.h</span> logging levels and usage guidance
> +
> +<span>[more to be added]</span>
>
> If changing an exported interface, please try to deprecate the interface in
> an orderly manner. If at all possible, try to retain the old deprecated
> @@ -64,13 +59,11 @@ interface as is, or functionally equivalent. Make a
> note of when the
> interface was deprecated and guard the deprecated interface definitions in
> the header file, i.e.:
>
> -\begin{verbatim}
> -/* Deprecated: 20050406 */
> -#if !defined(QUAGGA_NO_DEPRECATED_INTERFACES)
> -#warning "Using deprecated <libname> (interface(s)|function(s))"
> -...
> -#endif /* QUAGGA_NO_DEPRECATED_INTERFACES */
> -\end{verbatim}
> + /* Deprecated: 20050406 */
> + #if !defined(QUAGGA_NO_DEPRECATED_INTERFACES)
> + #warning "Using deprecated <libname> (interface(s)|function(s))"
> + ...
> + #endif /* QUAGGA_NO_DEPRECATED_INTERFACES */
>
> This is to ensure that the core Quagga sources do not use the deprecated
> interfaces (you should update Quagga sources to use new interfaces, if
> @@ -78,167 +71,147 @@ applicable), while allowing external sources to
> continue to build.
> Deprecated interfaces should be excised in the next unstable cycle.
>
> Note: If you wish, you can test for GCC and use a function
> -marked with the 'deprecated' attribute. However, you must provide the
> +marked with the ’deprecated’ attribute. However, you must provide the
> warning for other compilers.
>
> -If changing or removing a command definition, \emph{ensure} that you
> +If changing or removing a command definition, *ensure* that you
> properly deprecate it - use the \_DEPRECATED form of the appropriate DEFUN
> -macro. This is \emph{critical}. Even if the command can no longer
> -function, you \emph{MUST} still implement it as a do-nothing stub. +macro.
> This is *critical*. Even if the command can no longer
> +function, you *MUST* still implement it as a do-nothing stub.
>
> Failure to follow this causes grief for systems administrators, as an
> upgrade may cause daemons to fail to start because of unrecognised commands.
> Deprecated commands should be excised in the next unstable cycle. A list of
> deprecated commands should be collated for each release.
>
> -See also section~\ref{sec:dll-versioning} below regarding SHARED LIBRARY
> +See also section [sec:dll-versioning] below regarding SHARED LIBRARY
> VERSIONING.
>
> -\section{YOUR FIRST CONTRIBUTIONS}
> +YOUR FIRST CONTRIBUTIONS
> +========================
>
> Routing protocols can be very complex sometimes. Then, working with an
> Opensource community can be complex too, but usually friendly with
> anyone who is ready to be willing to do it properly.
>
> -\begin{itemize}
> +- First, start doing simple tasks. Quagga’s patchwork is a good place
> + to start with. Pickup some patches, apply them on your git trie,
> + review them and send your ack’t or review comments. Then, a
> + maintainer will apply the patch if ack’t or the author will have to
> + provide a new update. It help a lot to drain the patchwork queues.
> + See <http://patchwork.quagga.net/project/quagga/list/>
> +
> +- The more you’ll review patches from patchwork, the more the Quagga’s
> + maintainers will be willing to consider some patches you will be
> + sending.
>
> - \item First, start doing simple tasks. Quagga's patchwork is a good place
> - to start with. Pickup some patches, apply them on your git trie,
> - review them and send your ack't or review comments. Then, a
> - maintainer will apply the patch if ack't or the author will
> - have to provide a new update. It help a lot to drain the
> - patchwork queues.
> - See \url{http://patchwork.quagga.net/project/quagga/list/}
> +- start using git clone, pwclient
> + <http://patchwork.quagga.net/help/pwclient/>
>
> - \item The more you'll review patches from patchwork, the more the
> - Quagga's maintainers will be willing to consider some patches you
> will
> - be sending.
> + $ pwclient list -s new
> + ID State Name
> + -- ----- ----
> + 179 New [quagga-dev,6648] Re: quagga on FreeBSD 4.11
> (gcc-2.95)
> + 181 New [quagga-dev,6660] proxy-arp patch
> + [...]
>
> - \item start using git clone, pwclient
> \url{http://patchwork.quagga.net/help/pwclient/}
> + $ pwclient git-am 1046
>
> -\begin{verbatim}
> -$ pwclient list -s new
> -ID State Name
> --- ----- ----
> -179 New [quagga-dev,6648] Re: quagga on FreeBSD 4.11 (gcc-2.95)
> -181 New [quagga-dev,6660] proxy-arp patch
> -[...]
> +HANDY GUIDELINES FOR MAINTAINERS
> +================================
>
> -$ pwclient git-am 1046
> -\end{verbatim}
> +Get your cloned trie:
>
> -\end{itemize}
> + git clone [email protected]:/srv/git/quagga.git
>
> -\section{HANDY GUIDELINES FOR MAINTAINERS}
> +Apply some ack’t patches:
>
> -Get your cloned trie:
> -\begin{verbatim}
> - git clone [email protected]:/srv/git/quagga.git
> -\end{verbatim}
> -
> -Apply some ack't patches:
> -\begin{verbatim}
> - pwclient git-am 1046
> - Applying patch #1046 using 'git am'
> - Description: [quagga-dev,11595] zebra: route_unlock_node is missing in
> "show ip[v6] route <prefix>" commands
> - Applying: zebra: route_unlock_node is missing in "show ip[v6] route
> <prefix>" commands
> -\end{verbatim}
> -
> -Run a quick review. If the ack't was not done properly, you know who you have
> + pwclient git-am 1046
> + Applying patch #1046 using 'git am'
> + Description: [quagga-dev,11595] zebra: route_unlock_node is
> missing in "show ip[v6] route <prefix>" commands
> + Applying: zebra: route_unlock_node is missing in "show ip[v6]
> route <prefix>" commands
> +
> +Run a quick review. If the ack’t was not done properly, you know who you have
> to blame.
>
> Push the patches:
> -\begin{verbatim}
> - git push
> -\end{verbatim}
> +
> + git push
>
> Set the patch to accepted on patchwork
> -\begin{verbatim}
> - pwclient update -s Accepted 1046
> -\end{verbatim}
>
> -\section{COMPILE-TIME CONDITIONAL CODE}
> + pwclient update -s Accepted 1046
> +
> +COMPILE-TIME CONDITIONAL CODE
> +=============================
>
> Please think very carefully before making code conditional at compile time,
> as it increases maintenance burdens and user confusion. In particular,
> -please avoid gratuitous --enable-\ldots switches to the configure script -
> -typically code should be good enough to be in Quagga, or it shouldn't be
> -there at all. +please avoid gratuitous -–enable-… switches to the
> configure script -
> +typically code should be good enough to be in Quagga, or it shouldn’t be
> +there at all.
>
> When code must be compile-time conditional, try have the compiler make it
> conditional rather than the C pre-processor - so that it will still be
> checked by the compiler, even if disabled. I.e. this:
>
> -\begin{verbatim}
> - if (SOME_SYMBOL)
> - frobnicate();
> -\end{verbatim}
> + if (SOME_SYMBOL)
> + frobnicate();
>
> rather than:
>
> -\begin{verbatim}
> - #ifdef SOME_SYMBOL
> - frobnicate ();
> - #endif /* SOME_SYMBOL */
> -\end{verbatim}
> -
> -Note that the former approach requires ensuring that SOME\_SYMBOL will be
> -defined (watch your AC\_DEFINEs).
> + #ifdef SOME_SYMBOL
> + frobnicate ();
> + #endif /* SOME_SYMBOL */
>
> +Note that the former approach requires ensuring that SOME\_SYMBOL will
> +be defined (watch your AC\_DEFINEs).
>
> -\section{COMMIT MESSAGES}
> +COMMIT MESSAGES
> +===============
>
> The commit message requirements are:
>
> -\begin{itemize}
> +- The message *MUST* provide a suitable one-line summary followed by a
> + blank line as the very first line of the message, in the form:
>
> -\item The message \emph{MUST} provide a suitable one-line summary followed
> - by a blank line as the very first line of the message, in the form:
> + `topic: high-level, one line summary`
>
> - \verb|topic: high-level, one line summary|
> + Where topic would tend to be name of a subdirectory, and/or daemon,
> unless
> + there’s a more suitable topic (e.g. ’build’). This topic is used to
> + organise change summaries in release announcements.
>
> - Where topic would tend to be name of a subdirectory, and/or daemon, unless
> - there's a more suitable topic (e.g. 'build'). This topic is used to
> - organise change summaries in release announcements.
> +- It should have a suitable “body”, which tries to address the
> + following areas, so as to help reviewers and future browsers of the
> + code-base understand why the change is correct (note also the code
> + comment requirements):
>
> -\item It should have a suitable "body", which tries to address the
> - following areas, so as to help reviewers and future browsers of the
> - code-base understand why the change is correct (note also the code
> - comment requirements):
> -
> - \begin{itemize}
> - - \item The motivation for the change (does it fix a bug, if so which?
> + - The motivation for the change (does it fix a bug, if so which?
> add a feature?)
> - - \item The general approach taken, and trade-offs versus any other
> +
> + - The general approach taken, and trade-offs versus any other
> approaches.
> - - \item Any testing undertaken or other information affecting the
> confidence
> +
> + - Any testing undertaken or other information affecting the confidence
> that can be had in the change.
> - - \item Information to allow reviewers to be able to tell which specific
> +
> + - Information to allow reviewers to be able to tell which specific
> changes to the code are intended (and hence be able to spot any
> accidental
> unintended changes).
>
> - \end{itemize}
> -\end{itemize}
> -
> The one-line summary must be limited to 54 characters, and all other
> lines to 72 characters.
>
> Commit message bodies in the Quagga project have typically taken the
> following form:
>
> -\begin{itemize}
> -\item An optional introduction, describing the change generally.
> -\item A short description of each specific change made, preferably:
> - \begin{itemize} \item file by file
> - \begin{itemize} \item function by function (use of "ditto", or globs is
> - allowed)
> - \end{itemize}
> - \end{itemize}
> -\end{itemize}
> +- An optional introduction, describing the change generally.
> +
> +- A short description of each specific change made, preferably:
> +
> + - file by file
> +
> + - function by function (use of “ditto”, or globs is allowed)
>
> Contributors are strongly encouraged to follow this form.
>
> @@ -251,110 +224,109 @@ redundant. For longer patches, such a break-down
> may be essential. A
> contrived example (where the general discussion is obviously somewhat
> redundant, given the one-line summary):
>
> -\begin{quote}\begin{verbatim}
> -zebra: Enhance frob FSM to detect loss of frob
> -
> -Add a new DOWN state to the frob state machine to allow the barinator to
> -detect loss of frob.
> -
> -* frob.h: (struct frob) Add DOWN state flag.
> -* frob.c: (frob_change) set/clear DOWN appropriately on state change.
> -* bar.c: (barinate) Check frob for DOWN state.
> -\end{verbatim}\end{quote}
> +> zebra: Enhance frob FSM to detect loss of frob
> +>
> +> Add a new DOWN state to the frob state machine to allow the
> barinator to
> +> detect loss of frob.
> +>
> +> * frob.h: (struct frob) Add DOWN state flag.
> +> * frob.c: (frob_change) set/clear DOWN appropriately on state change.
> +> * bar.c: (barinate) Check frob for DOWN state.
>
> Please have a look at the git commit logs to get a feel for what the norms
> are.
>
> -Note that the commit message format follows git norms, so that ``git
> -log --oneline'' will have useful output.
> +Note that the commit message format follows git norms, so that “git log
> +–oneline” will have useful output.
>
> -\section{HACKING THE BUILD SYSTEM}
> +HACKING THE BUILD SYSTEM
> +========================
>
> If you change or add to the build system (configure.ac, any Makefile.am,
> etc.), try to check that the following things still work:
>
> -\begin{itemize}
> -\item make dist
> -\item resulting dist tarball builds
> -\item out-of-tree builds
> -\end{itemize}
> +- make dist
> +
> +- resulting dist tarball builds
> +
> +- out-of-tree builds
>
> The quagga.net site relies on make dist to work to generate snapshots. It
> must work. Common problems are to forget to have some additional file
> included in the dist, or to have a make rule refer to a source file without
> using the srcdir variable.
>
> +RELEASE PROCEDURE
> +=================
> +
> +- Tag the appropriate commit with a release tag (follow existing
> + conventions).
> +
> + [This enables recreating the release, and is just good CM practice.]
> +
> +- Create a fresh tar archive of the quagga.net repository, and do a
> + test build:
>
> -\section{RELEASE PROCEDURE}
> + vim configure.ac
> + git commit -m "release: 0.99.99.99"
> + git tag -u 54CD2E60 quagga-0.99.99.99
> + git push savannah tag quagga-0.99.99.99
>
> -\begin{itemize}
> -\item Tag the appropriate commit with a release tag (follow existing
> - conventions).
> - - [This enables recreating the release, and is just good CM practice.]
> + git archive --prefix=quagga-release/ quagga-0.99.99.99 | tar
> xC /tmp
> + git log quagga-0.99.99.98..quagga-0.99.99.99 > \
> + /tmp/quagga-release/quagga-0.99.99.99.changelog.txt
> + cd /tmp/quagga-release
>
> -\item Create a fresh tar archive of the quagga.net repository, and do a test
> - build:
> + autoreconf -i
> + ./configure
> + make
> + make dist-gzip
>
> - \begin{verbatim}
> - vim configure.ac
> - git commit -m "release: 0.99.99.99"
> - git tag -u 54CD2E60 quagga-0.99.99.99
> - git push savannah tag quagga-0.99.99.99
> + gunzip < quagga-0.99.99.99.tar.gz > quagga-0.99.99.99.tar
> + xz -6e < quagga-0.99.99.99.tar > quagga-0.99.99.99.tar.xz
> + gpg -u 54CD2E60 -a --detach-sign quagga-0.99.99.99.tar
>
> - git archive --prefix=quagga-release/ quagga-0.99.99.99 | tar xC /tmp
> - git log quagga-0.99.99.98..quagga-0.99.99.99 > \
> - /tmp/quagga-release/quagga-0.99.99.99.changelog.txt
> - cd /tmp/quagga-release
> + scp quagga-0.99.99.99.*
> [email protected]:/releases/quagga
> +
>
> - autoreconf -i
> - ./configure
> - make
> - make dist-gzip
> + Do NOT do this in a subdirectory of the Quagga sources, autoconf
> + will think it’s a sub-package and fail to include neccessary files.
>
> - gunzip < quagga-0.99.99.99.tar.gz > quagga-0.99.99.99.tar
> - xz -6e < quagga-0.99.99.99.tar > quagga-0.99.99.99.tar.xz
> - gpg -u 54CD2E60 -a --detach-sign quagga-0.99.99.99.tar
> +- Add the version number on https://bugzilla.quagga.net/, under
> + Administration, Products, “Quagga”, Edit versions, Add a version.
>
> - scp quagga-0.99.99.99.* [email protected]:/releases/quagga
> - \end{verbatim}
> +- Edit the wiki on
> + https://wiki.quagga.net/wiki/index.php/Release\_status
>
> - Do NOT do this in a subdirectory of the Quagga sources, autoconf will think
> - it's a sub-package and fail to include neccessary files.
> +- Post a news entry on Savannah
>
> -\item Add the version number on https://bugzilla.quagga.net/, under
> - Administration, Products, "Quagga", Edit versions, Add a version.
> -\item Edit the wiki on https://wiki.quagga.net/wiki/index.php/Release\_status
> -\item Post a news entry on Savannah
> -\item Send a mail to quagga-dev and quagga-users
> -\end{itemize}
> +- Send a mail to quagga-dev and quagga-users
>
> -The tarball which `make dist' creates is the tarball to be released! The
> -git-archive step ensures you're working with code corresponding to that in
> +The tarball which ‘make dist’ creates is the tarball to be released! The
> +git-archive step ensures you’re working with code corresponding to that in
> the official repository, and also carries out keyword expansion. If any
> errors occur, move tags as needed and start over from the fresh checkouts.
> Do not append to tarballs, as this has produced non-standards-conforming
> tarballs in the past.
>
> -See also: \url{http://wiki.quagga.net/index.php/Main/Processes}
> +See also: <http://wiki.quagga.net/index.php/Main/Processes>
>
> -[TODO: collation of a list of deprecated commands. Possibly can be scripted
> -to extract from vtysh/vtysh\_cmd.c]
> +[TODO: collation of a list of deprecated commands. Possibly can be
> +scripted to extract from vtysh/vtysh\_cmd.c]
>
> -
> -\section{TOOL VERSIONS}
> +TOOL VERSIONS
> +=============
>
> Require versions of support tools are listed in INSTALL.quagga.txt.
> Required versions should only be done with due deliberation, as it can
> cause environments to no longer be able to compile quagga.
>
> +SHARED LIBRARY VERSIONING {#sec:dll-versioning}
> +=========================
>
> -\section{SHARED LIBRARY VERSIONING}
> -\label{sec:dll-versioning}
> -
> -[this section is at the moment just gdt's opinion]
> +[this section is at the moment just gdt’s opinion]
>
> -Quagga builds several shared libaries (lib/libzebra, ospfd/libospf,
> +Quagga builds several shared libaries (lib/libzebra, ospfd/libospf,
> ospfclient/libsopfapiclient). These may be used by external programs,
> e.g. a new routing protocol that works with the zebra daemon, or
> ospfapi clients. The libtool info pages (node Versioning) explain
> @@ -372,162 +344,157 @@ There is no support intended for installing part of
> zebra. The core
> library libzebra and the included daemons should always be built and
> installed together.
>
> -
> -\section{GIT COMMIT SUBMISSION}
> -\label{sec:git-submission}
> +GIT COMMIT SUBMISSION {#sec:git-submission}
> +=====================
>
> The preferred method for submitting changes is to provide git commits via a
> publicly-accessible git repository, which the maintainers can easily pull.
>
> The commits should be in a branch based off the Quagga.net master - a
> -"feature branch". Ideally there should be no commits to this branch other
> +“feature branch”. Ideally there should be no commits to this branch other
> than those in master, and those intended to be submitted. However, merge
> commits to this branch from the Quagga master are permitted, though strongly
> discouraged - use another (potentially local and throw-away) branch to test
> merge with the latest Quagga master.
>
> Recommended practice is to keep different logical sets of changes on
> -separate branches - "topic" or "feature" branches. This allows you to still
> -merge them together to one branch (potentially local and/or "throw-away")
> +separate branches - “topic” or “feature” branches. This allows you to still
> +merge them together to one branch (potentially local and/or “throw-away”)
> for testing or use, while retaining smaller, independent branches that are
> easier to merge.
>
> -All content guidelines in section \ref{sec:patch-submission}, PATCH
> +All content guidelines in section [sec:patch-submission], PATCH
> SUBMISSION apply.
>
> +PATCH SUBMISSION {#sec:patch-submission}
> +================
>
> -\section{PATCH SUBMISSION}
> -\label{sec:patch-submission}
> -
> -\begin{itemize}
> -
> -\item For complex changes, contributors are strongly encouraged to first
> - start a design discussion on the quagga-dev list \emph{before}
> - starting any coding.
> -
> -\item Send a clean diff against the 'master' branch of the quagga.git
> - repository, in unified diff format, preferably with the '-p'
> argument to
> - show C function affected by any chunk, and with the -w and -b
> arguments to
> - minimise changes. E.g:
> +- For complex changes, contributors are strongly encouraged to first
> + start a design discussion on the quagga-dev list *before* starting
> + any coding.
>
> - git diff -up mybranch..remotes/quagga.net/master
> +- Send a clean diff against the ’master’ branch of the quagga.git
> + repository, in unified diff format, preferably with the ’-p’
> + argument to show C function affected by any chunk, and with the -w
> + and -b arguments to minimise changes. E.g:
>
> - It is preferable to use git format-patch, and even more preferred to
> - publish a git repository (see GIT COMMIT SUBMISSION, section
> - \ref{sec:git-submission}).
> + git diff -up mybranch..remotes/quagga.net/master
>
> - If not using git format-patch, Include the commit message in the email.
> + It is preferable to use git format-patch, and even more preferred to
> + publish a git repository (see GIT COMMIT SUBMISSION, section
> + [sec:git-submission]).
>
> -\item After a commit, code should have comments explaining to the reviewer
> - why it is correct, without reference to history. The commit message
> - should explain why the change is correct.
> + If not using git format-patch, Include the commit message in the
> + email.
>
> -\item Include NEWS entries as appropriate.
> +- After a commit, code should have comments explaining to the reviewer
> + why it is correct, without reference to history. The commit message
> + should explain why the change is correct.
>
> -\item Include only one semantic change or group of changes per patch.
> +- Include NEWS entries as appropriate.
>
> -\item Do not make gratuitous changes to whitespace. See the w and b arguments
> - to diff.
> +- Include only one semantic change or group of changes per patch.
>
> -\item Changes should be arranged so that the least controversial and most
> - trivial are first, and the most complex or more controversial are
> - last. This will maximise how many the Quagga maintainers can merge,
> - even if some other commits need further work.
> +- Do not make gratuitous changes to whitespace. See the w and b
> + arguments to diff.
>
> -\item Providing a unit-test is strongly encouraged. Doing so will make it
> - much easier for maintainers to have confidence that they will be able
> - to support your change.
> +- Changes should be arranged so that the least controversial and most
> + trivial are first, and the most complex or more controversial are
> + last. This will maximise how many the Quagga maintainers can merge,
> + even if some other commits need further work.
>
> -\item New code should be arranged so that it easy to verify and test. E.g.
> - stateful logic should be separated out from functional logic as much as
> - possible: wherever possible, move complex logic out to smaller helper
> - functions which access no state other than their arguments.
> +- Providing a unit-test is strongly encouraged. Doing so will make it
> + much easier for maintainers to have confidence that they will be
> + able to support your change.
>
> -\item State on which platforms and with what daemons the patch has been
> - tested. Understand that if the set of testing locations is small,
> - and the patch might have unforeseen or hard to fix consequences that
> - there may be a call for testers on quagga-dev, and that the patch
> - may be blocked until test results appear.
> +- New code should be arranged so that it easy to verify and test. E.g.
> + stateful logic should be separated out from functional logic as much
> + as possible: wherever possible, move complex logic out to smaller
> + helper functions which access no state other than their arguments.
>
> - If there are no users for a platform on quagga-dev who are able and
> - willing to verify -current occasionally, that platform may be
> - dropped from the "should be checked" list.
> +- State on which platforms and with what daemons the patch has been
> + tested. Understand that if the set of testing locations is small,
> + and the patch might have unforeseen or hard to fix consequences that
> + there may be a call for testers on quagga-dev, and that the patch
> + may be blocked until test results appear.
>
> -\end{itemize}
> + If there are no users for a platform on quagga-dev who are able and
> + willing to verify -current occasionally, that platform may be
> + dropped from the “should be checked” list.
>
> -\section{PATCH APPLICATION}
> +PATCH APPLICATION
> +=================
>
> -\begin{itemize}
> +- Only apply patches that meet the submission guidelines.
>
> -\item Only apply patches that meet the submission guidelines.
> +- If the patch might break something, issue a call for testing on the
> + mailing-list.
>
> -\item If the patch might break something, issue a call for testing on the
> - mailing-list.
> +- Give an appropriate commit message (see above), and use the –author
> + argument to git-commit, if required, to ensure proper attribution
> + (you should still be listed as committer)
>
> -\item Give an appropriate commit message (see above), and use the --author
> - argument to git-commit, if required, to ensure proper attribution (you
> - should still be listed as committer)
> +- Immediately after commiting, double-check (with git-log and/or
> + gitk). If there’s a small mistake you can easily fix it with ‘git
> + commit –amend ..’
>
> -\item Immediately after commiting, double-check (with git-log and/or gitk).
> - If there's a small mistake you can easily fix it with `git commit
> - --amend ..'
> +- When merging a branch, always use an explicit merge commit. Giving
> + –no-ff ensures a merge commit is created which documents “this human
> + decided to merge this branch at this time”.
>
> -\item When merging a branch, always use an explicit merge commit. Giving
> - --no-ff ensures a merge commit is created which documents ``this human
> - decided to merge this branch at this time''.
> -\end{itemize}
> -
> -\section{STABLE PLATFORMS AND DAEMONS}
> +STABLE PLATFORMS AND DAEMONS
> +============================
>
> The list of platforms that should be tested follow. This is a list
> derived from what quagga is thought to run on and for which
> maintainers can test or there are people on quagga-dev who are able
> and willing to verify that -current does or does not work correctly.
>
> -\begin{itemize}
> - \item BSD (Free, Net or Open, any platform)
> - \item GNU/Linux (any distribution, i386)
> - \item Solaris (strict alignment, any platform)
> - \item future: NetBSD/sparc64
> -\end{itemize}
> +- BSD (Free, Net or Open, any platform)
> +
> +- GNU/Linux (any distribution, i386)
> +
> +- Solaris (strict alignment, any platform)
> +
> +- future: NetBSD/sparc64
>
> The list of daemons that are thought to be stable and that should be
> tested are:
>
> -\begin{itemize}
> - \item zebra
> - \item bgpd
> - \item ripd
> - \item ospfd
> - \item ripngd
> -\end{itemize}
> +- zebra
> +
> +- bgpd
> +
> +- ripd
> +
> +- ospfd
> +
> +- ripngd
> +
> Daemons which are in a testing phase are
>
> -\begin{itemize}
> - \item ospf6d
> - \item isisd
> - \item watchquagga
> -\end{itemize}
> +- ospf6d
>
> -\section{IMPORT OR UPDATE VENDOR SPECIFIC ROUTING PROTOCOLS}
> +- isisd
> +
> +- watchquagga
> +
> +IMPORT OR UPDATE VENDOR SPECIFIC ROUTING PROTOCOLS
> +==================================================
>
> The source code of Quagga is based on two vendors:
>
> - \verb|zebra_org| (\url{http://www.zebra.org/})
> - \verb|isisd_sf| (\url{http://isisd.sf.net/})
> +`zebra_org` (<http://www.zebra.org/>) `isisd_sf`
> +(<http://isisd.sf.net/>)
>
> To import code from further sources, e.g. for archival purposes without
> -necessarily having to review and/or fix some changeset, create a branch from
> -`master':
> +necessarily having to review and/or fix some changeset, create a branch
> +from ‘master’:
>
> -\begin{verbatim}
> - git checkout -b archive/foo master
> - <apply changes>
> - git commit -a "Joe Bar <[email protected]>"
> - git push quagga archive/foo
> -\end{verbatim}
> + git checkout -b archive/foo master
> + <apply changes>
> + git commit -a "Joe Bar <[email protected]>"
> + git push quagga archive/foo
>
> -presuming `quagga' corresponds to a file in your .git/remotes with
> +presuming ‘quagga’ corresponds to a file in your .git/remotes with
> configuration for the appropriate Quagga.net repository.
> -
> -\end{document}
>
>
>
> _______________________________________________
> Quagga-dev mailing list
> [email protected]
> https://lists.quagga.net/mailman/listinfo/quagga-dev
>
--
Network Ability Ltd. | Chief Technical Officer | Tel: +353 1 6169698
52 Lower Sandwith St | INEX - Internet Neutral |
Dublin 2, Ireland | Exchange Association | Email: [email protected]
_______________________________________________
Quagga-dev mailing list
[email protected]
https://lists.quagga.net/mailman/listinfo/quagga-dev
