pidgin/nest
Add community.md and design-guidelines.md
+++ b/community.md Mon Sep 18 22:27:00 2017 -0500
@@ -0,0 +1,116 @@
+Being a communication project we can be found all over the place. Below you can find the specifics.
+Yes! For general questions about using Pidgin, problems connecting, etc. please use the [support mailing list](http://pidgin.im/cgi-bin/mailman/listinfo/support).
+If you're a developer and want to ask about the internals of libpurple, Pidgin, Finch, or GNT, please use the [devel mailing list](http://pidgin.im/cgi-bin/mailman/listinfo/devel).
+We offer a few other mailing lists, too. See the full list [here](http://pidgin.im/cgi-bin/mailman/listinfo).
+Yes! We especially need small patches for small bugs, and lots of bug triaging. There are a slew of a bug reports in Pidgin's ticket system - you could pick one and try to tackle it and submit a patch. We love patches!
+Bug triaging is when you look at a bug report and determine whether it is a duplicate of an earlier report, or whether it is user error, or maybe you need to request additional information to be able to reproduce the bug. We don't allow people to modify ticket attributes, but if you leave a *helpful* comment on the ticket with your findings, we will take appropriate action. This is a *significant* help to us, because it allows fewer people to have to focus primarily on maintenance of the ticket system, while other development resources are spent as well as they can be.
+You are more than welcome to ask, but be prepared for the answer to be something like "ask the authors". We simply don't have the time or energy to keep up with all of the third-party projects out there, so we probably can't help you. Common topics that fall into this category are various encryption plugins, GFire, and various Purple Plugin Pack plugins.
+ * XMPP (a.k.a. Jabber), SIMPLE, and IRC are published protocols, so we didn't need to reverse-engineer them. (Google Talk is an implementation of XMPP.)
+ * MSN was at one time a published protocol; over time changes have creeped into the protocol and other people have reverse engineered those newer revisions.
+ These days, almost all chat protocols are encrypted between the client and the server. We'll assume that you're asking about end-to-end encryption: when only the two people having the conversation have access to its unencrypted contents.
+ The SILC protocol is natively encrypted. For other protocols, which do not natively support encryption, neither do we. Simply encrypting the data stream with no verification of the parties involved in the conversation is not secure in any sense of the word. Some other clients offer options like this, but we feel that such measures instill a false sense of security that is more harmful than helpful.
+ Note that there are a number of third-party plugin developers working on secure IM frameworks. Take a look at the [ThirdPartyPlugins](third-party-plugins.md) page for links to those we know of.
+~~The schedule for releases is every third Thursday~~. However, a new version will only be released if it meets a certain standard of quality (i.e., it will not be released if it still has a large number of serious bugs). Therefore, some releases will take longer than others. Major rewrites means lots of new bugs to work out. The new version will be released as soon as it is possible to do so. The [Roadmap](https://developer.pidgin.im/roadmap) gives best-guess estimates, but take them with a grain of salt--if we aren't ready to release on a Milestone's due date, we won't release, and that milestone will fall into "past due."
+Starting with version 1.0.0, Pidgin version numbers have 3 parts to them. The format is major.minor.micro. If we change something internally in Pidgin such that some plugins won't work with the newer version, we will increment the major version number. If we don't increment the major version number, and we've added things to the Pidgin API that won't break any older stuff, we will increment the minor version number. In any other cases, we will increment the micro version number. Even and odd numbers have nothing to do with stability, and you should always be running the latest release of Pidgin to get new features and bug fixes.
+Pidgin, with a capital P, or pidgin, with a little p. In all cases, the remainder of the letters are lowercase. It's not PIDGIN, nor PidGin, nor PiDgIn, nor anything similar. Stop doing that.
+[Pidgin](http://dictionary.reference.com/browse/pidgin) is not, in fact, named *after* so-called "rats with wings," but rather it refers to a special type of "broken" language used by speakers of different languages to communicate. We thought this name fit well with the purpose of Pidgin.
+Of course, Pidgin is a [homonym](http://dictionary.reference.com/browse/homonym) for pigeon, so we couldn't resist taking advantage of the pun to create a cartoon mascot.
+Many have subsequently pointed out that the use of carrier pigeons for transmission of messages fits nicely with Pidgin's functionality as well.
+The use of the term purple is another [homonym](http://dictionary.reference.com/browse/homonym) of sorts. Long ago, we started referring to PRotocol PLugins by an abbreviated name "PrPl" which we would pronounce in the same manner as the color. Since libpurple provides primarily an interface for using protocol plugins to access a variety of IM networks, it seemed reasonable that we name the library after the pronounciation.
+In keeping with bird theming for IM clients based upon libpurple, including [Adium](https://adium.im) (the Duck client), and [Pidgin](https://pidgin.im) (the Pigeon client), Finch was chosen as the name for our text-based client.
+Occasionally we, the Pidgin team, receive requests to remove information from our mailing list archives. We don’t honor those requests. Quite frankly, by the time we get the request it’s already too late for removal to be useful.
+Every post to our mailing lists is archived. Our archives are public. A number of other mailing list archival services have been subscribed to our lists, making duplicated archives that we have no control over.
+Google and other search engines index our archives, which we also have no control over. (Yes, robots.txt exists, but search engines are not obligated to obey it, and we actually want our archives indexed so our users can find information more easily.)
+By the time we receive a request to remove any data from our archives, it already exists in so many places that one more copy of the data can’t possibly cause any additional harm. We also do include a disclaimer on the list info page for each of our mailing lists and in the Help->About box in Pidgin itself that our mailing lists are publicly archived, thus adequate warning exists to inform people that their data will be publicly disclosed.
+++ b/design-guidelines.md Mon Sep 18 22:27:00 2017 -0500
@@ -0,0 +1,42 @@
+These guidelines are informal descriptions of the sort of thinking that goes into the design of Pidgin, libpurple, and family. These are not hard-and-fast rules, but they are conscious decisions made by the Pidgin developers which will be violated only after careful consideration. (Or by mistake, and corrected shortly thereafter!)
+While Pidgin is a multiprotocol IM client, the goal is to hide protocols from the user as much as possible. Obviously users have to know about individual protocols when they create or modify accounts, but in day-to-day communication and usage, the intent is that users don't have to think about protocols at all.
+The workflow in Pidgin is intended to be "I would like to chat with Sean about wibbles", not "I would like to create an XMPP conversation with seanegan@pidgin.im".
+The focus is on the goal, not the process. In reaching toward this focus, we have chosen to paper over the differences between the various protocols and features as much as possible (without crippling or needlessly complicating things). This has lead to decisions such as the removal of protocol icons from the buddy list and the implementation of contact-aware chats and logs.
+> Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
+In general we try to keep the code and the user interface simple. Especially when it comes to preferences in the UI. Pidgin should be as streamlined as possible. It is an IM client, so messaging someone should be easy. See [this essay](http://www106.pair.com/rhp/free-software-ui.html) by Havoc Pennington for an explanation of some ideas that we try to follow.
+It's important for the code to be simple because this is an open source project and developers come and go. You never know who's going to be looking at your code next. If you write a function that's hard to follow then the next person that comes along will end up rewriting it, and that's counterproductive.
+In plain language, this means that the protocol-specific code goes in the protocol plugin (*prpl*), and that libpurple exists, and is cleanly separated from the user interface. There are practical implications to this. While all of our code depends on glib, only the Pidgin specific parts depend on GTK+.
+To implement, for example, file transfer; there are 3 steps. First, the protocol(s) have to support it. By themselves, however, the protocols can do nothing. So the "core," libpurple, has to support it also (the second step).
+We do not want massive amounts of very similar code in libpurple, so the implementation of file transfer at the libpurple level has to abstract away from how individual protocols handle it, so as to be able to use the same calls from all file transfer supporting protocols.
+Last, but not least, before the user can actually send or receive a file, the UI (Pidgin, Finch, or Adium) must support it. These interfaces know nothing about the protocol, and have only limited contact with the core. This helps to enforce the desire for uniformity explained above. It also makes it easier for the only sort of duplication we encourage: many interfaces. The core implementation cannot assume too much about what the UI will do, because the GTK+ UI (Pidgin) might need to handle a file transfer somewhat differently than the ncurses based UI (Finch).
+Patches that voilate this layering will be rejected. In practice, this means that there is more work involved to introduce a new class of functionality, say file transfer, white-boarding, voice, or video. On the other hand, it means less work to implement any given class of functionality for a new protocol or for a new UI.
+Our source code is very much a 'live' document. It should reflect what is currently needed, not what used to be needed or what might be needed in the future. Old code should be removed if it isn't being used (of course, you can only remove public functions and structures when the major version number increases)--it'll always be in the source code repository if anyone needs it. The code should contain documentation about what it does and why.
+Pidgin and libpurple are single threaded. That means that the network code runs in the same process as the user interface. Network code must be non-blocking, otherwise the UI will be unresponsive. Code should be event-driven. Long running tasks should be asynchronous. File descriptors that need to be watched for changes should be added to the event loop.