Merge pull request #290 from jorol/help-modules

gh#238 add help module Contribution, Development_Setup & Patch_Submis…
LibreCat · Feb 27, 2017 · 4abeb01 · 4abeb01
2 parents a675ad4 + 9833b80
commit 4abeb01
Show file tree

Hide file tree

Showing 4 changed files with 304 additions and 10 deletions.
diff --git a/lib/Catmandu/Help/Contribution.pm b/lib/Catmandu/Help/Contribution.pm
@@ -0,0 +1,146 @@
+1;
+
+=pod
+
+=encoding utf8
+
+=head1 Contribution
+
+This guide has been written to help anyone interested in contributing to the development of Catmandu. Please read this guide before contributing to Catmandu or related projects, to avoid wasted effort and maximizing the chances of your contributions being used.
+
+=head2 Ways to contribute
+
+There are many ways to contribute to the project: report bugs, write  documentation, submit patches or implement new features. Catmandu is a young yet active project and any kind of help is very much appreciated!
+
+=head3 Publicity
+
+You don't have to start by hacking the code, spreading the word is very valuable as well!
+
+If you have a blog, just feel free to speak about Catmandu.
+
+Of course, it doesn't have to be limited to blogs or Twitter. Feel free to spread the word in whatever way you consider fit and drop us a line on the Catmandu user mailing list noted below.
+
+Also, if you're using and enjoying Catmandu, L<rating us on cpanratings.perl.org|http://cpanratings.perl.org/dist/Catmandu>, explaining what you like about Catmandu is another very valuable contribution that helps other new users find us!
+
+=head3 Mailing list
+
+Subscribing to the mailing list and providing assistance to new users is incredibly valuable.
+
+=over
+
+=item Mailing list: I<librecat-dev@lists.uni-bielefeld.de>
+
+=item Subscribe or view archives here: L<https://lists.uni-bielefeld.de/mailman2/cgi/unibi/listinfo/librecat-dev>
+
+=back
+
+=head3 Documentation
+
+We value documentation very much, but it's difficult to keep it up-to-date. If you find a typo or an error in the documentation please do let us know - ideally by submitting a patch (pull request) with your fix or suggestion (see L<Catmandu::Help::Patch_Submission>).
+
+=head3 Code
+
+To can contribute to Catmandu's core code or extend the functionality by new L<Importers|https://metacpan.org/search?q=Catmandu%3A%3AImporter>, L<Exporters|https://metacpan.org/search?q=Catmandu%3A%3AExporter>, L<Stores|https://metacpan.org/search?q=Catmandu%3A%3AStore>, L<Fix packages|https://metacpan.org/search?q=Catmandu%3A%3AFix>, L<Validators|https://metacpan.org/pod/Catmandu::Validator>, L<Binds|https://metacpan.org/search?q=Catmandu%3A%3AFix%3A%3ABind>, or L<Plugins|https://metacpan.org/search?q=Catmandu%3A%3APlugin>. Have a look at the list of L<missing modules|https://github.com/LibreCat/Catmandu/wiki/Missing-modules> for existing ideas and resources for new Catmandu modules. Feel also free to add new ideas and links there.
+
+For more detailed guidelines, see:
+
+=over
+
+=item L<Catmandu::Help::Development_Setup> for how to set up a development environment
+
+=item L<Catmandu::Help::Patch_Submission> for how to submit patches using the GitHub workflow
+
+=item L<Catmandu::Help::Coding_Guidelines> for how to write readable code and documentation
+
+=back
+
+=head2 Quality Supervision and Reporting Bugs
+
+We can measure our quality using the several platforms:
+
+=over
+
+=item L<CPAN Testers|http://www.cpantesters.org>
+
+=item L<Travis CI|https://travis-ci.org/LibreCat/>
+
+=item L<Coveralls|https://coveralls.io/github/LibreCat/>
+
+A good way to help the project is to find a failing build log on the CPAN testers: L<CPAN Testers Matrix|http://www.cpantesters.org/distro/D/Catmandu.html>
+
+If you find a failing test report or another kind of bug, feel free to report it as a GitHub issue: L<http://github.com/LibreCat/Catmandu/issues>. Please make sure the bug you're reporting does not yet exist.
+
+=head2 Resources for Developers
+
+=head3 Website
+
+The official website is here: L<http://librecat.org/>. A Wordpress blog with hints is available at: L<https://librecatproject.wordpress.com/>
+
+=head3 Mailing Lists
+
+A mailing list is available here: I<librecat-dev@mail.librecat.org>
+
+=head3 Repositories
+
+The official repository is hosted on GitHub at L<http://github.com/LibreCat/Catmandu>.
+
+Official developers have write access to this repository, contributors are
+invited to fork the dev branch (!) and submit a pull request, as described 
+at L<Patch Submission|/"Patch Submission">.
+
+=head3 Core Maintainers
+
+=over
+
+=item L<Catmandu|https://metacpan.org/pod/Catmandu> - @nics
+=item L<Catmandu::AWS|https://metacpan.org/pod/Catmandu::AWS> - @phochste
+=item L<Catmandu::AlephX|https://metacpan.org/pod/Catmandu::AlephX> - @nicolasfranck
+=item L<Catmandu::ArXiv|https://metacpan.org/pod/Catmandu::ArXiv> - @pietsch, @vpeil
+=item L<Catmandu::Atom|https://metacpan.org/pod/Catmandu::Atom> - @phochste
+=item L<Catmandu::BibTeX|https://metacpan.org/pod/Catmandu::BibTeX> - @pietsch, @vpeil
+=item L<Catmandu::Cmd::fuse|https://metacpan.org/pod/Catmandu::Cmd::fuse> - @nics
+=item L<Catmandu::Cmd::repl|https://metacpan.org/pod/Catmandu::Cmd::repl> - @pietsch
+=item L<Catmandu::CrossRef|https://metacpan.org/pod/Catmandu::CrossRef> -@pietsch, @vpeil
+=item L<Catmandu::DBI|https://metacpan.org/pod/Catmandu::DBI> - @nicolasfranck
+=item L<Catmandu::DSpace|https://metacpan.org/pod/Catmandu::DSpace> - @nicolasfranck
+=item L<Catmandu::EuropePMC|https://metacpan.org/pod/Catmandu::EuropePMC> - @vpeil
+=item L<Catmandu::Exporter::ODS|https://metacpan.org/pod/Catmandu::Exporter::ODS> - @snorri
+=item L<Catmandu::Exporter::RTF|https://metacpan.org/pod/Catmandu::Exporter::RTF> - @petrakohorst
+=item L<Catmandu::Exporter::Template|https://metacpan.org/pod/Catmandu::Exporter::Template> - @vpeil
+=item L<Catmandu::FedoraCommons|https://metacpan.org/pod/Catmandu::FedoraCommons> - @phochste
+=item L<Catmandu::Fix::XML|https://metacpan.org/pod/Catmandu::Fix::XML> - @nichtich
+=item L<Catmandu::Fix::cmd|https://metacpan.org/pod/Catmandu::Fix::cmd> - @nichtich
+=item L<Catmandu::Importer::CPAN|https://metacpan.org/pod/Catmandu::Importer::CPAN> - @nichtich @phochste
+=item L<Catmandu::Importer::Parltrack|https://metacpan.org/pod/Catmandu::Importer::Parltrack> - @jonas
+=item L<Catmandu::Inspire|https://metacpan.org/pod/Catmandu::Inspire> - @vpeil
+=item L<Catmandu::LDAP|https://metacpan.org/pod/Catmandu::LDAP> - @nics
+=item L<Catmandu::MARC|https://metacpan.org/pod/Catmandu::MARC> - @phochste
+=item L<Catmandu::MediaMosa|https://metacpan.org/pod/Catmandu::MediaMosa> - @nicolasfranck
+=item L<Catmandu::OAI|https://metacpan.org/pod/Catmandu::OAI> - @pietsch, @phochste
+=item L<Catmandu::ORCID|https://metacpan.org/pod/Catmandu::ORCID> - @pietsch
+=item L<Catmandu::PLoS|https://metacpan.org/pod/Catmandu::PLoS> - @pietsch, @vpeil
+=item L<Catmandu::Plack-REST|https://metacpan.org/pod/Catmandu::Plack-REST>  - @phochste
+=item L<Catmandu::PubMed|https://metacpan.org/pod/Catmandu::PubMed> - @pietsch, @vpeil
+=item L<Catmandu::RDF|https://metacpan.org/pod/Catmandu::RDF> - @nichtich
+=item L<Catmandu::SRU|https://metacpan.org/pod/Catmandu::SRU> - @pietsch
+=item L<Catmandu::Serializer::messagepack|https://metacpan.org/pod/Catmandu::Serializer::messagepack> - @nicolasfranck
+=item L<Catmandu::Serializer::storable|https://metacpan.org/pod/Catmandu::Serializer::storable> - @nics
+=item L<Catmandu::Store:CouchDB|https://metacpan.org/pod/Catmandu::Store:CouchDB> - @nics
+=item L<Catmandu::Store::Elasticsearch|https://metacpan.org/pod/Catmandu::Store::Elasticsearch> - @nics
+=item L<Catmandu::Store::Lucy|https://metacpan.org/pod/Catmandu::Store::Lucy> - @nics
+=item L<Catmandu::Store::MongoDB|https://metacpan.org/pod/Catmandu::Store::MongoDB> - @nics
+=item L<Catmandu::Store::Solr|https://metacpan.org/pod/Catmandu::Store::Solr> - @nicolasfranck , @nics
+=item L<Catmandu::Twitter|https://metacpan.org/pod/Catmandu::Twitter> - @pietsch
+=item L<Catmandu::XLS|https://metacpan.org/pod/Catmandu::XLS> - @jorol, @nics
+=item L<Catmandu::Z3950|https://metacpan.org/pod/Catmandu::Z3950> - @pietsch
+=item L<Dancer:Plugin::Auth::RBAC::Credentials:Catmandu|https://metacpan.org/pod/Dancer:Plugin::Auth::RBAC::Credentials:Catmandu> - @nicolasfranck
+=item L<Dancer::Plugin::Catmandu::OAI|https://metacpan.org/pod/Dancer::Plugin::Catmandu::OAI> - @nicolasfranck
+=item L<Dancer::Plugin::Catmandu::SRU|https://metacpan.org/pod/Dancer::Plugin::Catmandu::SRU> - @nics, phochste
+=item L<Dancer::Session::Catmandu|https://metacpan.org/pod/Dancer::Session::Catmandu> - @nics
+=item L<LibreCat::Sitemap|https://metacpan.org/pod/LibreCat::Sitemap> - @phochste
+=item L<MODS::Record|https://metacpan.org/pod/MODS::Record> - @phochste
+=item L<Plack::Session::Store::Catmandu|https://metacpan.org/pod/Plack::Session::Store::Catmandu> - @nics
+=item L<Task::Catmandu|https://metacpan.org/pod/Task::Catmandu> - @nics
+=item L<WWW::ORCID|https://metacpan.org/pod/WWW::ORCID> - @nics
+
+=back
diff --git a/lib/Catmandu/Help/Development_Setup.pm b/lib/Catmandu/Help/Development_Setup.pm
@@ -0,0 +1,76 @@
+1;
+
+=pod
+
+=encoding utf8
+
+=head1 Development Setup
+
+The following guidelines describe how to set up a development environment for L<contribution|Catmandu::Help::Contribution> of code.
+
+=head2 Set up a development environment
+
+If you want to submit a patch for Catmandu, you need git and very likely also `milla` (L<Dist::Milla>). We also recommend L<perlbrew|https://perlbrew.pl/> (see below) to test and develop Catmandu on a recent version of perl. We also suggest L<App::cpanminus>) to quickly and comfortably install perl modules under I<perlbrew>.
+
+In the following sections we provide tips for the installation of some of these tools together with L<Catmandu>. Please also see the documentation that comes with these tools for more info.
+
+=head3 Perlbrew tips (Optional)
+
+Install I<perlbrew> for example with 
+    
+    cpanm App::perlbrew
+
+Check which perls are available
+
+    perlbrew available
+
+At the time of writing it looks like this
+
+    perl-5.18.0
+    perl-5.16.3
+    perl-5.14.4
+    perl-5.12.5
+    perl-5.10.1
+    perl-5.8.9
+    perl-5.6.2
+    perl5.005_04
+    perl5.004_05
+    perl5.003_07
+
+Then go on and install a version inside Perlbrew. I recommend you give a name
+to the installation (`--as` option), as well as compiling without the tests
+(`--n` option) to speed it up.
+
+    perlbrew install -n perl-5.16.3 --as catmandu_dev -j 3
+
+Wait a while, and it should be done. Switch to your new Perl with:
+
+    perlbrew switch catmandu_dev
+
+Now you are using the fresh Perl, you can check it with:
+
+    which perl
+
+Install cpanm on your brewed version of perl:
+
+    perlbrew install-cpanm
+
+
+=head3 Get Catmandu sources
+
+Get the Catmandu sources from github (for a more complete git workflow see 
+below):
+
+Clone your fork to have a local copy using the following command:
+
+    $ git clone git@github.com:LibreCat/Catmandu.git
+
+The installation is then straight forward:
+
+    $ cd Catmandu
+    $ perl Build.PL
+    $ ./Build
+    $ ./Build test
+    $ ./Build install
+
+You can now start with hacking Catmandu and L<patch submission|Catmandu::Help::Patch_Submission>!
diff --git a/lib/Catmandu/Help/Installation.pm b/lib/Catmandu/Help/Installation.pm
@@ -33,7 +33,6 @@ You probably want to install more Catmandu tools like L<Catmandu::OAI>, L<Catman
     $ cpanm Catmandu::Store::MongoDB
     $ cpanm Catmandu::XLS
 
-
 To make full usage of the capabilities of Catmandu, database and search engines such as MongoDB, Elasticsearch, Solr, Postgres, MySQL can be installed on the system with the corresponding Catmandu tools. How to install these database on your local system falls outside the scope of this documentation. Please consult the installation guide of the database product for more information. For more information on the available Catmandu packages consult our L<Distributions|http://librecat.org/distributions.html> list.
 
 Here are some Catmandu installation hints for various platforms.
@@ -92,13 +91,11 @@ Alternatively, you can build newest Catmandu as unofficial packages, using most
     $ sudo dpkg -i libcatmandu-twitter-perl_*.deb
     $ sudo dpkg -i ~/.cpan/build/libcatmandu-*-perl_*.deb
 
-
 =head2 Ubuntu Server
 
     $ sudo apt-get install build-essential libmodule-install-perl perl-doc libgdbm-dev libwrap0-dev libssl-dev libyaz-dev zlib1g zlib1g-dev libxml2-dev libexpat1-dev libxslt1-dev
     $ cpanm Catmandu
 
-
 =head2 CentOS 
 
 =head3 Version 6.4
@@ -123,13 +120,10 @@ Alternatively, you can build newest Catmandu as unofficial packages, using most
 
 =head2 OpenBSD 53
 
-
     $ cpanm Catmandu
 
-
 =head2 OSX
 
-
     $ brew install libxml++ libxml2 xml2 libxslt
     # Install plenv from https://github.com/tokuhirom/plenv
     $ git clone https://github.com/tokuhirom/plenv.git ~/.plenv
@@ -145,27 +139,23 @@ Alternatively, you can build newest Catmandu as unofficial packages, using most
     $ cpanm Catmandu
     $ plenv rehash
 
-
 =head2 Windows 
 
 We recommend to use L<Strawberry Perl|http://strawberryperl.com/> on Windows systems. After installation just run the follwing command from the I<cmd> shell:
 
     $ cpanm Catmandu
 
-
 =head2 Raspbian GNU/Linux 7 on the Raspberry Pi (armhf)
 
 Since Raspbian is based on Debian stable, you could follow the L<instructions|/Debian> there. Unfortunately, you will run into timeouts, so it is advisable to install some prerequisites via apt-get first:
 
     $ sudo apt-get install libboolean-perl libdevel-repl-perl libnet-twitter-perl 
     $ sudo apt-get install libxml-easy-perl libxslt1-dev libgdbm-dev
 
-
 =head2 Windows, Mac OSX, Linux 
 
 A L<docker image of Catmandu|https://registry.hub.docker.com/u/librecat/catmandu/> is build with each release. After L<installation of docker|https://docs.docker.com/installation/#installation> get and use the Catmandu image like this:
 
-
     # Upgrade to the latest version
     $ docker pull librecat/catmandu
 

diff --git a/lib/Catmandu/Help/Patch_Submission.pm b/lib/Catmandu/Help/Patch_Submission.pm
@@ -0,0 +1,82 @@
+1;
+
+=pod
+
+=encoding utf8
+
+=head1 Patch Submission
+
+The Catmandu development team uses GitHub to collaborate. We greatly appreciate L<contributions|Catmandu::Help::Contribution> submitted via L<GitHub|https://github.com/LibreCat>, as it makes tracking these contributions and applying them much, much easier. This gives your contribution a much better chance of being integrated into Catmandu quickly!
+
+To help us achieve high-quality, stable releases, git-flow workflow is used to handle pull-requests, that means contributors must work on their I<dev> branch rather than on their I<master> (the I<master> branch should be touched only by the core dev team when preparing a release to CPAN; all ongoing development happens in branches which are merged to the I<dev> branch.)
+
+Here is the workflow for submitting a patch:
+
+=head2 1. Fork
+
+Fork the repository L<http://github.com/LibreCat/Catmandu> (click "Fork")
+
+=head2 2. Clone
+
+Clone your fork to have a local copy using the following command:
+
+    $ git clone git://github.com/$myname/Catmandu.git
+
+=head2 3. Development branch
+
+As a contributor, you should B<always> work on the I<dev> branch of your clone (I<master> is used only for building releases).
+
+    $ git remote add upstream https://github.com/LibreCat/Catmandu.git
+    $ git fetch upstream
+    $ git checkout -b dev upstream/dev
+
+This will create a local branch in your clone named I<dev> and that will track the official I<dev> branch. That way, if you have more or less commits than the upstream repo, you'll be immediately notified by git.
+
+=head2 4. Topic branch
+
+You want to isolate all your commits in a I<topic> branch, this will make the reviewing much easier for the core team and will allow you to continue working on your clone without worrying about different commits mixing together.
+
+To do that, first create a local branch to build your pull request:
+
+    # you should be in dev branch here
+    $ git checkout -b pr/$name
+
+Now you have created a local branch named I<pr/$name> where I<$name> is the name you want (it should describe the purpose of the pull request you're preparing).
+
+=head2 5. Push
+
+In that branch, do all the commits you need (the more the better) and when
+   done, push the branch to your fork:
+
+    # ... commits ...
+    $ git push origin pr/$name
+
+You are now ready to send a pull request.
+
+=head2 6. Pull request
+
+Send a I<pull request> via the GitHub interface. Make sure your pull request is based on the I<pr/$name> branch you've just pushed, so that it incorporates the appropriate commits only.
+
+It's also a good idea to summarize your work in a report sent to the users mailing list (see below), in order to make sure the team is aware of it.
+
+When the core team reviews your pull request, it will either accept (and then merge into I<dev>) or refuse your request.
+
+If it's refused, try to understand the reasons explained by the team for the denial. Most of the time, communicating with the core team is enough to understand what the mistake was. Above all, please don't be offended.
+
+=head2 7. Merge
+
+If your pull-request is merged into I<dev>, then all you have to do is to remove your local and remote I<pr/$name> branch:
+
+    $ git checkout dev
+    $ git branch -D pr/$name
+    $ git push origin :pr/$name
+
+=head2 8. Pull
+
+And then, of course, you need to sync your local I<dev> branch with the I<upstream>:
+
+    $ git pull upstream dev
+    $ git push origin dev
+
+You're now ready to start working on a new pull request!
+