diff --git a/docs/doc-src/CodingGuidelines.rst b/docs/doc-src/CodingGuidelines.rst deleted file mode 100644 index 92cc3be..0000000 --- a/docs/doc-src/CodingGuidelines.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. -*- coding: utf-8 -*- -.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap -.. _OLI_git_repo: git://github.com/OfflineIMAP/offlineimap.git - -================================= -Coding guidelines for OfflineIMAP -================================= - -.. contents:: -.. .. sectnum:: - -This document contains assorted guidelines for programmers that want -to hack OfflineIMAP. - - ------------------- -Exception handling ------------------- - -OfflineIMAP on many occasions re-raises various exceptions and often -changes exception type to `OfflineImapError`. This is not a problem -per se, but you must always remember that we need to preserve original -tracebacks. This is not hard if you follow these simple rules. - -For re-raising original exceptions, just use:: - - raise - -from inside your exception handling code. - -If you need to change exception type, or its argument, or whatever, -use this three-argument form:: - - raise YourExceptionClass(argum, ents), None, sys.exc_info()[2] - -In this form, you're creating an instance of new exception, so ``raise`` -will deduce its ``type`` and ``value`` parameters from the first argument, -thus the second expression passed to ``raise`` is always ``None``. -And the third one is the traceback object obtained from the thread-safe -``exc_info()`` function. - -In fact, if you hadn't already imported the whole ``sys`` module, it will -be better to import just ``exc_info()``:: - - from sys import exc_info - -and raise like this:: - - raise YourExceptionClass(argum, ents), None, exc_info()[2] - -since this is the historically-preferred style in the OfflineIMAP code. diff --git a/docs/doc-src/GitAdvanced.rst b/docs/doc-src/GitAdvanced.rst deleted file mode 100644 index 402f68d..0000000 --- a/docs/doc-src/GitAdvanced.rst +++ /dev/null @@ -1,684 +0,0 @@ -.. -*- coding: utf-8 -*- -.. vim: spelllang=en ts=2 expandtab: - -.. _OfflineIMAP: http://offlineimap.org -.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project -.. _Developers's Certificate of Origin: https://github.com/OfflineIMAP/offlineimap/blob/next/docs/doc-src/dco.rst - -============ -Git Advanced -============ - -.. contents:: :depth: 2 - -Git: OfflineImap's branching Model And Workflow -=============================================== - - -Git Branching model -------------------- - -OfflineIMAP_ uses the following branches: - -master - This is **the mainline**. Simple users should use this branch. - -next - **The development branch** for developers and testers. The content of ``next`` is - merged into the mainline ``master`` at release time for both stable and releases - candidates. When patches are sent to the mailing list, contributors discuss - about them. Once done and when patches looks ready for the mainline, patches - are first merged into ``next``. Advanced developers and testers use this branch to - test the last merged patches before they hit the mainline. This helps not - introducing strong breakages directly in the mainline. - -maint - This is **the maintenance branch**. It gets its own releases starting off of an old - stable release. - Notice that this branch tend to be more or less abandoned when context does not - force the maintainers to take care of it. - -pu - Don't care much about this branch unless you're asked to use it. It's almost - abandoned nowadays. ``pu`` stands for *"proposed updates"* and helps - **tracking of topics**. If a topic is not ready for the ``next`` release, it - might be merged into ``pu``. This branch only help developers to work on - someone else topic or an earlier pending topic. Developers can extract a topic - from this branch to work on it. This branch is **not intended to be - checkouted**; never. Even developers don't do that. Due to the way ``pu`` is - built you can't expect content there to work in any way... unless you clearly - want to run into troubles. - - -Release cycles --------------- - -A typical release cycle works like this: - -1. A stable release is out. - -2. Feature topics are sent, discussed and merged. - -3. When enough work was merged, we start the freeze cycle: the first release - candidate is out. - -4. During the freeze cycle, no more features are merged. It's time to test - OfflineIMAP_. The more we are late in *-rc* releases, the less patches are - merged but bug fixes. - -5. When we think a release is stable enough, we restart from step 1. - - -Because third-parties tend to not always follow the cycles, it's fine to send -your patches as soon as they are ready. Any maintainer might prefer to pend your -contributions before merging it at a better time. You'll always be notified if -such decision is made for your work. - -Know about where we are in the release cycle:: - - $ git tag - - -Create commits --------------- - -* Make commits of logical units. -* If you change, add, or remove a command line option or - make some other user interface change, the associated - documentation should be updated as well. -* Check for unnecessary whitespace with ``git diff --check`` - before committing. -* Do not check in commented out code or unneeded files. -* the first line of the commit message should be a short - description (50 characters is the soft limit, see DISCUSSION - in git-commit(1)), and should skip the full stop -* The body should provide a meaningful commit message, which: - * uses the imperative, present tense: **change**, - not **changed** or **changes**; - * includes motivation for the change, and contrasts - its implementation with previous behaviour. -* Add a ``Signed-off-by: Your Name `` line to - to confirm that you agree to the `Developer's Certificate of Origin`_. -* Make sure that you have tests for the bug you are fixing. -* Make sure that the test suite passes after your commit. - - -Make a pull request -------------------- - -* Push your changes to a topic branch in your public fork of OfflineIMAP. -* Submit a pull request to the OfflineIMAP_ maintainers. -* If a ticket is open in the issues, add a comment with the link to your pull - request. - - -Export commits as patches -------------------------- - -* Use ``git format-patch -M`` to create the patch. -* Do not attach your patch, but read in the mail - body, unless you cannot teach your mailer to - leave the formatting of the patch alone. -* Be careful doing cut & paste into your mailer, not to - corrupt whitespaces. - - -Export commits as patches (experts) ------------------------------------ - -* Do not PGP sign your patch. -* Provide additional information (which is unsuitable for - the commit message) between the ``---`` and the diffstat. -* If your name is not writable in ASCII, make sure that - you send off a message in the correct encoding. -* Send the patch to the `mailing list`_ if (and only if) - the patch is ready for inclusion. -* If you use `git-send-email(1)` which is a good idea, - please test it first by sending email to yourself. -* See below for instructions specific to your mailer. - - -Extract a topic from pu ------------------------ - -To find the tip of a topic branch, run ``git log --first-parent next..pu`` and -look for the merge commit. The second parent of this commit is the tip of the -topic branch. - - -``pu`` is built this way:: - - $ git checkout pu - $ git reset --keep next - $ git merge --no-ff -X theirs topic1 - $ git merge --no-ff -X theirs topic2 - $ git merge --no-ff -X theirs blue - $ git merge --no-ff -X theirs orange - ... - -As a consequence: - -1. Each topic merged uses a merge commit. A merge commit is a commit having 2 - ancestors. Actually, Git allows more than 2 parents but we don't use this - feature. It's intended. - -2. Paths in ``pu`` may mix up multiple versions if all the topics don't use the same - base commit. This is very often the case as topics aren't rebased: it guarantees - each topic is strictly identical to the last version sent to the mailing list. - No surprise. - - -What you need to extract a particular topic is the *sha1* of the tip of that -branch (the last commit of the topic). Assume you want the branch of the topic -called 'blue'. First, look at the log given by this command:: - - $ git log --reverse --merges --parents origin/next..origin/pu - -With this command you ask for the log: - -* from next to pu -* in reverse order (older first) -* merge commits only -* with the sha1 of the ancestors - -From this list, find the topic you're looking for, basing you search on the lines -like:: - - Merge branch 'topic/name' into pu - -By convention, it has the form /. When you're at -it, pick the topic ancestor sha1. It's always the last sha1 in the line starting -by 'commit'. For you to know: - -* The first sha1 is the commit you see: the merge commit. -* The following sha1 is the ancestor of the branch checkouted at merge time - (always the previous merged topic or the ancien next in our case). -* Last is the branch merged. - -Giving:: - - commit sha1_of_merge_commit sha1_of_ancient_pu sha1_of_topic_blue - -Then, you only have to checkout the topic from there:: - - $ git checkout -b blue sha1_of_topic_blue - -You're done! You've just created a new branch called "blue" with the blue -content. Be aware this topic is not updated against the **current** next branch. -,-) - - - -Very detailed version -===================== - -I started reading over the SubmittingPatches document for Git, primarily because -I wanted to have a document similar to it for OfflineIMAP to make sure people -understand what they are doing when they write `Signed-off-by` line. - -But the patch submission requirements are a lot more relaxed here on the -technical/contents front, because the OfflineIMAP is a lot smaller ;-). So here -are only the relevant bits. - - -Decide what branch to base your work on ---------------------------------------- - -In general, base your work on the ``next`` branch. Otherwise, start off of the -latest commit your change is relevant to. - - -Make separate commits for logically separate changes ----------------------------------------------------- - -Unless your patch is really trivial, you should not be sending your -changes in a single patch. Instead, always make a commit with -complete commit message and generate a series of small patches from -your repository. - -Describe the technical detail of the change(s). - -If your description starts to get too long, that's a sign that you probably need -to split up your commit to finer grained pieces. That being said, patches which -plainly describe the things that help reviewers check the patch, and future -maintainers understand the code, are the most beautiful patches. - -Descriptions that summarise the point in the subject well, and describe the -motivation for the change, the approach taken by the change, and if relevant how -this differs substantially from the prior version, can be found on Usenet -archives back into the late 80's. Consider it like good Netiquette, but for -code. - - -Generate your patch using git tools out of your commits -------------------------------------------------------- - -* ``git`` based diff tools (git, Cogito, and StGIT included) generate *unidiff* -which is the preferred format. - -* You do not have to be afraid to use ``-M`` option to ``git diff`` or ``git -format-patch``, if your patch involves file renames. The receiving end can -handle them just fine. - -* Please make sure your patch does not include any extra files which do not -belong in a patch submission. - -* Make sure to review your patch after generating it, to ensure accuracy. - -* Before sending out, please make sure it cleanly applies to the ``next`` branch -head. If you are preparing a work based on somewhere else, that is fine, but -please mark it as such. - - -Sending your patches --------------------- - -The mailing list is the preferred way for sending patches. This allows easier -review and comments on the code. - -People on the mailing list need to be able to read and -comment on the changes you are submitting. It is important for -a developer to be able to "quote" your changes, using standard -e-mail tools, so that they may comment on specific portions of -your code. For this reason, all patches should be submitted -"inline". WARNING: Be wary of your MUAs word-wrap -corrupting your patch. Do not cut-n-paste your patch; you can -lose tabs that way if you are not careful. - -It is a common convention to prefix your subject line with -[PATCH]. This lets people easily distinguish patches from other -e-mail discussions. Use of additional markers after PATCH and -the closing bracket to mark the nature of the patch is also -encouraged. E.g. [PATCH/RFC] is often used when the patch is -not ready to be applied but it is for discussion, [PATCH v2], -[PATCH v3] etc. are often seen when you are sending an update to -what you have previously sent. - -* ``git format-patch`` command follows the best current practice to - format the body of an e-mail message. At the beginning of the - patch should come your commit message, ending with the - ``Signed-off-by:`` lines, a line that consists of three dashes, - followed by the diffstat information and the patch itself. - -* If you are forwarding a patch from somebody else, optionally, at - the beginning of the e-mail message just before the commit - message starts, you can put a ``From:`` line to name that person. - -* You often want to add additional explanation about the patch, - other than the commit message itself. Place such "cover letter" - material between the three dash lines and the diffstat. - -* Do not attach the patch as a MIME attachment, compressed or not. - Many popular e-mail applications will not always - transmit a MIME attachment as plain text, making it impossible to comment on - your code. A MIME attachment also takes a bit more time to process. This does - not decrease the likelihood of your MIME-attached change being accepted, but it - makes it more likely that it will be postponed. - - Exception: If your mailer is mangling patches then someone may ask - you to re-send them using MIME, that is OK. - -* Do not let your e-mail client send quoted-printable. - -* Do not let your e-mail client send format=flowed which would destroy -whitespaces in your patches. - -* Do not PGP sign your patch, at least for now. Most likely, your - maintainer or other people on the list would not have your PGP - key and would not bother obtaining it anyway. Your patch is not - judged by who you are; a good patch from an unknown origin has a - far better chance of being accepted than a patch from a known, - respected origin that is done poorly or does incorrect things. - - If you really really really really want to do a PGP signed - patch, format it as "multipart/signed", not a text/plain message - that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is - not a text/plain, it's something else. - -* Unless your patch is a very trivial and an obviously correct one, - first send it with "To:" set to the mailing list, with "cc:" listing - people who are involved in the area you are touching (the output from - "git blame $path" and "git shortlog --no-merges $path" would help to - identify them), to solicit comments and reviews. After the list - reached a consensus that it is a good idea to apply the patch, re-send - it with "To:" set to the maintainer and optionally "cc:" the list for - inclusion. Do not forget to add trailers such as "Acked-by:", - "Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as - necessary. - - -Sign your work --------------- - -To improve tracking of who did what, we've borrowed the -"sign-off" procedure from the Linux kernel project on patches -that are being emailed around. Although OfflineIMAP is a lot -smaller project it is a good discipline to follow it. - -The sign-off is a simple line at the end of the explanation for -the patch, which **certifies that you wrote it or otherwise have -the right to pass it on as a open-source patch**. The rules are -pretty simple: if you can certify the below: - - -An ideal patch flow -=================== - -Here is an ideal patch flow for this project the current maintainers -suggests to the contributors: - -0. You come up with an itch. You code it up. - -1. Send it to the list and cc people who may need to know about - the change. - - The people who may need to know are the ones whose code you - are butchering. These people happen to be the ones who are - most likely to be knowledgeable enough to help you, but - they have no obligation to help you (i.e. you ask for help, - don't demand). ``git log -p -- $area_you_are_modifying`` would - help you find out who they are. - -2. You get comments and suggestions for improvements. You may - even get them in a "on top of your change" patch form. - -3. Polish, refine, and re-send to the list and the people who - spend their time to improve your patch. Go back to step (2). - -4. The list forms consensus that the last round of your patch is - good. Send it to the list and cc the maintainers. - -5. A topic branch is created with the patch and is merged to ``next``, - and cooked further and eventually graduates to ``master``. - - -In any time between the (2)-(3) cycle, the maintainer may pick it up -from the list and queue it to ``pu``, in order to make it easier for -people play with it without having to pick up and apply the patch to -their trees themselves. - - -Know the status of your patch after submission ----------------------------------------------- - -You can use Git itself to find out when your patch is merged in -master. ``git pull --rebase`` will automatically skip already-applied -patches, and will let you know. This works only if you rebase on top -of the branch in which your patch has been merged (i.e. it will not -tell you if your patch is merged in ``pu`` if you rebase on top of -``next``). - -.. Read the git mailing list, the maintainer regularly posts messages - entitled "What's cooking in git.git" and "What's in git.git" giving - the status of various proposed changes. - - -MUA specific hints -================== - -Some of patches I receive or pick up from the list share common -patterns of breakage. Please make sure your MUA is set up -properly not to corrupt whitespaces. Here are two common ones -I have seen: - -* Empty context lines that do not have _any_ whitespace. - -* Non empty context lines that have one extra whitespace at the - beginning. - -One test you could do yourself if your MUA is set up correctly is: - -* Send the patch to yourself, exactly the way you would, except - To: and Cc: lines, which would not contain the list and - maintainer address. - -* Save that patch to a file in UNIX mailbox format. Call it say - a.patch. - -* Try to apply to the tip of the "master" branch from the - git.git public repository:: - - $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply - $ git checkout test-apply - $ git reset --hard - $ git am a.patch - -If it does not apply correctly, there can be various reasons. - -* Your patch itself does not apply cleanly. That is _bad_ but - does not have much to do with your MUA. Please rebase the - patch appropriately. - -* Your MUA corrupted your patch; "am" would complain that - the patch does not apply. Look at .git/rebase-apply/ subdirectory and - see what 'patch' file contains and check for the common - corruption patterns mentioned above. - -* While you are at it, check what are in 'info' and - 'final-commit' files as well. If what is in 'final-commit' is - not exactly what you would want to see in the commit log - message, it is very likely that your maintainer would end up - hand editing the log message when he applies your patch. - Things like "Hi, this is my first patch.\n", if you really - want to put in the patch e-mail, should come after the - three-dash line that signals the end of the commit message. - - -Pine ----- - -(Johannes Schindelin) - I don't know how many people still use pine, but for those poor souls it may - be good to mention that the quell-flowed-text is needed for recent versions. - - ... the "no-strip-whitespace-before-send" option, too. AFAIK it was introduced - in 4.60. - -(Linus Torvalds) - And 4.58 needs at least this - -:: - - --- - diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) - Author: Linus Torvalds - Date: Mon Aug 15 17:23:51 2005 -0700 - - Fix pine whitespace-corruption bug - - There's no excuse for unconditionally removing whitespace from - the pico buffers on close. - - diff --git a/pico/pico.c b/pico/pico.c - --- a/pico/pico.c - +++ b/pico/pico.c - @@ -219,7 +219,9 @@ PICO *pm; - switch(pico_all_done){ /* prepare for/handle final events */ - case COMP_EXIT : /* already confirmed */ - packheader(); - +#if 0 - stripwhitespace(); - +#endif - c |= COMP_EXIT; - break; - -(Daniel Barkalow) - > A patch to SubmittingPatches, MUA specific help section for - > users of Pine 4.63 would be very much appreciated. - - Ah, it looks like a recent version changed the default behavior to do the - right thing, and inverted the sense of the configuration option. (Either - that or Gentoo did it.) So you need to set the - "no-strip-whitespace-before-send" option, unless the option you have is - "strip-whitespace-before-send", in which case you should avoid checking - it. - - -Thunderbird ------------ - -(A Large Angry SCM) - By default, Thunderbird will both wrap emails as well as flag them as - being 'format=flowed', both of which will make the resulting email unusable - by git. - - Here are some hints on how to successfully submit patches inline using - Thunderbird. - - There are two different approaches. One approach is to configure - Thunderbird to not mangle patches. The second approach is to use - an external editor to keep Thunderbird from mangling the patches. - -**Approach #1 (configuration):** - - This recipe is current as of Thunderbird 2.0.0.19. Three steps: - - 1. Configure your mail server composition as plain text - Edit...Account Settings...Composition & Addressing, - uncheck 'Compose Messages in HTML'. - 2. Configure your general composition window to not wrap - Edit..Preferences..Composition, wrap plain text messages at 0 - 3. Disable the use of format=flowed - Edit..Preferences..Advanced..Config Editor. Search for: - mailnews.send_plaintext_flowed - toggle it to make sure it is set to 'false'. - - After that is done, you should be able to compose email as you - otherwise would (cut + paste, git-format-patch | git-imap-send, etc), - and the patches should not be mangled. - -**Approach #2 (external editor):** - -This recipe appears to work with the current [*1*] Thunderbird from Suse. - -The following Thunderbird extensions are needed: - AboutConfig 0.5 - http://aboutconfig.mozdev.org/ - External Editor 0.7.2 - http://globs.org/articles.php?lng=en&pg=8 - - -1) Prepare the patch as a text file using your method of choice. - -2) Before opening a compose window, use Edit->Account Settings to - uncheck the "Compose messages in HTML format" setting in the - "Composition & Addressing" panel of the account to be used to send the - patch. [*2*] - -3) In the main Thunderbird window, _before_ you open the compose window - for the patch, use Tools->about:config to set the following to the - indicated values:: - - mailnews.send_plaintext_flowed => false - mailnews.wraplength => 0 - -4) Open a compose window and click the external editor icon. - -5) In the external editor window, read in the patch file and exit the - editor normally. - -6) Back in the compose window: Add whatever other text you wish to the - message, complete the addressing and subject fields, and press send. - -7) Optionally, undo the about:config/account settings changes made in - steps 2 & 3. - - -[Footnotes] - -*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse -9.3 professional updates. - -*2* It may be possible to do this with about:config and the following -settings but I haven't tried, yet:: - - mail.html_compose => false - mail.identity.default.compose_html => false - mail.identity.id?.compose_html => false - -(Lukas Sandström) - There is a script in contrib/thunderbird-patch-inline which can help you - include patches with Thunderbird in an easy way. To use it, do the steps above - and then use the script as the external editor. - -Gnus ----- - -'|' in the *Summary* buffer can be used to pipe the current -message to an external program, and this is a handy way to drive -"git am". However, if the message is MIME encoded, what is -piped into the program is the representation you see in your -*Article* buffer after unwrapping MIME. This is often not what -you would want for two reasons. It tends to screw up non ASCII -characters (most notably in people's names), and also -whitespaces (fatal in patches). Running 'C-u g' to display the -message in raw form before using '|' to run the pipe can work -this problem around. - - -KMail ------ - -This should help you to submit patches inline using KMail. - -1) Prepare the patch as a text file. - -2) Click on New Mail. - -3) Go under "Options" in the Composer window and be sure that - "Word wrap" is not set. - -4) Use Message -> Insert file... and insert the patch. - -5) Back in the compose window: add whatever other text you wish to the - message, complete the addressing and subject fields, and press send. - - -Gmail ------ - -GMail does not appear to have any way to turn off line wrapping in the web -interface, so this will mangle any emails that you send. You can however -use "git send-email" and send your patches through the GMail SMTP server, or -use any IMAP email client to connect to the google IMAP server and forward -the emails through that. - -To use ``git send-email`` and send your patches through the GMail SMTP server, -edit `~/.gitconfig` to specify your account settings:: - - [sendemail] - smtpencryption = tls - smtpserver = smtp.gmail.com - smtpuser = user@gmail.com - smtppass = p4ssw0rd - smtpserverport = 587 - -Once your commits are ready to be sent to the mailing list, run the -following commands:: - - $ git format-patch --cover-letter -M origin/master -o outgoing/ - $ edit outgoing/0000-* - $ git send-email outgoing/* - -To submit using the IMAP interface, first, edit your `~/.gitconfig` to specify your -account settings:: - - [imap] - folder = "[Gmail]/Drafts" - host = imaps://imap.gmail.com - user = user@gmail.com - pass = p4ssw0rd - port = 993 - sslverify = false - -You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error -that the "Folder doesn't exist". - -Once your commits are ready to be sent to the mailing list, run the -following commands:: - - $ git format-patch --cover-letter -M --stdout origin/master | git imap-send - -Just make sure to disable line wrapping in the email client (GMail web -interface will line wrap no matter what, so you need to use a real -IMAP client). diff --git a/docs/doc-src/dco.rst b/docs/doc-src/dco.rst index 83ae888..ad8a3b0 100644 --- a/docs/doc-src/dco.rst +++ b/docs/doc-src/dco.rst @@ -1,3 +1,4 @@ +.. _dco Developer's Certificate of Origin ================================= diff --git a/docs/doc-src/index.rst b/docs/doc-src/index.rst index 89f9ff0..fb8bdc9 100644 --- a/docs/doc-src/index.rst +++ b/docs/doc-src/index.rst @@ -5,6 +5,9 @@ Welcome to OfflineIMAP's developer documentation ================================================ +**License** + :doc:`dco` (dco) + **Documented APIs** .. toctree::