From 9fb791a06a2dae82f15af16f629c6ad766cbfb4e Mon Sep 17 00:00:00 2001 From: Austin Ziegler Date: Mon, 19 Apr 2010 01:03:52 -0400 Subject: [PATCH] Documentation preparation for version 0.2 release. --- Hacking.rdoc | 69 ++++++++++++++++++++++++++++++++++++++--------- History.txt | 6 +++-- README.txt | 76 ++++++++++++++++++++++++++++------------------------ Rakefile | 1 + 4 files changed, 102 insertions(+), 50 deletions(-) diff --git a/Hacking.rdoc b/Hacking.rdoc index d17f1ca..736b32b 100644 --- a/Hacking.rdoc +++ b/Hacking.rdoc @@ -1,16 +1,59 @@ = Hacking Net::LDAP -We welcome your contributions to Net::LDAP. To increase the chances of your -patches being accepted, we recommend that you follow the guidelines below: +We welcome your contributions to Net::LDAP. We accept most contributions, but +there are ways to increase the chance of your patch being accepted quickly. -1. Your code should be formatted like the rest of Net::LDAP. We use a text - wrap of 76 - 78 characters, especially for documentation contents. - Operators should have spaces around them, method definitions should have - parentheses around arguments. Keep the indentation as flat as possible. -2. Your changes should be well-documented and described. -3. You must provide rspec tests for any new or changed features. Rspec has - been chosen as the way forward for tests. -4. You should provide LDIF data for importing into LDAP servers so that the - changes can be tested in situ with more than one real LDAP - server. -5. You should have tested your changes against a real LDAP server. +== Licensing + +Net::LDAP 0.3 and later will be licensed under an MIT-style license; any +contributions after 2010-04-20 must be under this license to be accepted. + +== Formatting + +* Your patches should be formatted like the rest of Net::LDAP. +* We use a text wrap of 76–78 characters, especially for documentation + contents. +* Operators should have spaces around them. +* Method definitions should have parentheses around arguments (and no + parentheses if there are no arguments). +* Indentation should be kept as flat as possible; this may mean being more + explicit with constants. + +== Documentation + +* Documentation: net-ldap[http://net-ldap.rubyforge.org/] + +It is very important that, if you add new methods or objects, your code is +well-documented. The purpose of the changes should be clearly described so that +even if this is a feature we do not use, we can understand its purpose. + +We also encourage documentation-only contributions that improve the +documentation of Net::LDAP. + +== Tests + +The Net::LDAP team uses RSpec for unit testing; all changes must have rspec +tests for any new or changed features. + +Your changes should have been tested against at least one real LDAP server; the +current tests are not sufficient to find all possible bugs. It's unlikely that +they will ever be sufficient given the variations in LDAP server behaviour. + +If you're introducing a new feature, it would be useful to provide LDIF data +for importing into LDAP servers for testing. + +== Development Dependencies + +Net::LDAP uses several libraries during development, all of which can be +installed using RubyGems. + +* *hoe* +* *hoe-git* +* *archive-tar-minitar* +* *metaid* + +== Participation + +* RubyForge: net-ldap[http://rubyforge.org/projects/net-ldap] +* GitHub: RoryO/ruby-net-ldap[http://github.com/RoryO/ruby-net-ldap/] +* Group: ruby-ldap[http://groups.google.com/group/ruby-ldap] diff --git a/History.txt b/History.txt index b066a73..9bfdbdb 100644 --- a/History.txt +++ b/History.txt @@ -1,4 +1,6 @@ -=== Net::LDAP NEXT / 2010-__-__ +=== Net::LDAP 0.2 / 2010-04-__ +* Added a document describing how to contribute to Net::LDAP most effectively. +* Preparing for a license change for Net::LDAP in the next release. * SSL capabilities will be enabled or disabled based on whether we can load OpenSSL successfully or not. * Moved the core class extensions extensions from being in the Net::LDAP @@ -38,7 +40,7 @@ === Net::LDAP 0.1.1 / 2010-03-18 * Fixing a critical problem with sockets. -=== Net::LDAP 0.1.0 / 2010-03-17 +=== Net::LDAP 0.1 / 2010-03-17 * Small fixes throughout, more to come. * Ruby 1.9 support added. * Ruby 1.8.6 and below support removed. If we can figure out a compatible way diff --git a/README.txt b/README.txt index c598633..b6ff0aa 100644 --- a/README.txt +++ b/README.txt @@ -2,48 +2,54 @@ == Description -Pure Ruby LDAP library. +Net::LDAP for Ruby (also called "net-ldap") is a pure-Ruby LDAP support +library that has been tested against several modern servers, including +OpenLDAP and Active Directory. It supports most LDAP client features and +a subset of server features. + +LDAP (Lightweight Directory Access Protocol) is an Internet protocol for +accessing distributed directory services. LDAP is often used to provide +access and authentication to networked services. + +The current release is mostly compliant with RFCs 2251–2256, 2829–2830, +3377, and 3771. Our roadmap for Net::LDAP 1.0 is to gain full +client compliance with the most recent IETF LDAP RFCs +(4510–4519, plus portions of 4520–4532). + +=== Notice of Impending License Change + +In the next release of Net::LDAP (0.3), we will be changing the license +to an MIT-style license. == Where -=== Issues & Project Homepage +* RubyForge: net-ldap[http://rubyforge.org/projects/net-ldap] +* GitHub: RoryO/ruby-net-ldap[http://github.com/RoryO/ruby-net-ldap/] +* Group: ruby-ldap[http://groups.google.com/group/ruby-ldap] +* Documentation: net-ldap[http://net-ldap.rubyforge.org/] -http://rubyforge.org/projects/net-ldap - -=== Code - -http://github.com/RoryO/ruby-net-ldap/ - -== FEATURES/PROBLEMS - -The Lightweight Directory Access Protocol (LDAP) is an Internet protocol for -accessing distributed directory services. - -Net::LDAP is an LDAP support library written in pure Ruby. It supports most -LDAP client features and a subset of server features as well. - -* Standards-based (going for RFC 4511) -* Portable: 100% Ruby - -== SYNOPSIS - -See Net::LDAP for documentation and usage samples. - -== REQUIREMENTS +== Requirements Net::LDAP requires Ruby 1.8.7-compliant interpreter or better. -== INSTALL +== Install + +Net::LDAP is a pure Ruby library. It does not require any external +compiled libraries. -Net::LDAP is a pure Ruby library. It does not require any external libraries. You can install the RubyGems version of Net::LDAP available from the usual sources. -* gem install net-ldap + gem install net-ldap -Simply require 'net/ldap'. +Simply require either 'net-ldap' or 'net/ldap'. -== CREDITS +For non-RubyGems installations of Net::LDAP, you can use Minero Aoki's +{setup.rb}[http://i.loveruby.net/en/projects/setup/] as the layout of +Net::LDAP is compliant. The setup installer is not included in the +Net::LDAP repository. + +== Credits Net::LDAP was originally developed by: @@ -58,13 +64,13 @@ Contributions since: * Dimitrij Denissenko dimdenis@rubyforge.org * "nowhereman" on GitHub -== LICENSE +== License Copyright (C) 2006 - 2010 by Francis Cianfrocca and other contributors. -Please read the file LICENSE for licensing restrictions on this library. In -the simplest terms, this library is available under the same terms as Ruby -itself. +Please read the file LICENSE for licensing restrictions on this library. +In the simplest terms, this library is available under the same terms as +Ruby itself. -Available under the same terms as Ruby. See LICENSE in the main distribution -for full licensing information. +Available under the same terms as Ruby. See LICENSE in the main +distribution for full licensing information. diff --git a/Rakefile b/Rakefile index ca9739a..137e716 100644 --- a/Rakefile +++ b/Rakefile @@ -33,6 +33,7 @@ Hoe.spec PKG_NAME do self.description = paragraphs_of(self.readme_file, 2..2).join("\n\n") extra_rdoc_files << MANIFEST.grep(/\.rdoc$/) + extra_rdoc_files.flatten! extra_dev_deps << [ "archive-tar-minitar", "~>0.5.1" ] extra_dev_deps << [ "hoe-git", "~>1" ]