Home

Awesome

###Status Build Status

Perl Maven

These are the source files of the articles published on http://perlmaven.com/ and its sub-domains.

The source code of the application running on the server can be found in the https://github.com/szabgab/Perl-Maven repository.

Copyright

All the original English articles are copyright Gabor Szabo, except where the =author field has the name of someone else. In those cases the person listed in the =author field owns the copyright. The translated articles are copyright the translator as mentioned in the =translator field and the original author as mentioned in the =author field.

License

All the Perl 5 examples are "free software". You can redistribute them under the same terms as Perl 5.10.

The articles and the translations are licensed as CC BY-NC-ND http://creativecommons.org/licenses/by-nc-nd/3.0/

FORMAT

See https://github.com/szabgab/Perl-Maven/blob/master/docs/FORMAT.md

Add an 128x128 image of you to the static/img/ folder and an entry for yourself in the authors.txt file in the root of the repository.

TRANSLATIONS - LOCALIZATION

Each language has a subdirectory in the sites/ folder.

Initial language codes were a bit random, but we will try to stick to the way Wikipedia describes: https://meta.wikimedia.org/wiki/List_of_Wikipedias

The translation process:

Comments

We use https://disqus.com/ as the commenting system. The English version is moderated by Gabor. If you'd like to enable comments on your language, and if you are willing to moderate it then please create an account on https://disqus.com/ and tell Gabor about it.

Moderation requires that you follow all the comments that arrive to the site and see if they need any attention. Spams are usually filtered by Disqus, but a few can slip through and there can be an occasional false positive, something that is marked as spam but it isn't really. The moderator also has to make sure that the comments stay civil and not hesitate to remove irrelevant or offending comments.

Getting started with the translation

PROMOTION

When articles are published they are posted to Google+, Twitter and sometimes even to Facebook. They are also posted on LinkedIN.

An e-mail is sent out to the people who registered on the Perl Maven site.

Many of the articles are included the Perl Weekly newsletter.

Once in a while I post a link to Reddit ( http://www.reddit.com/ ) but I'd rather see others post there if they find the article worth the mention. The same with Hacker News: https://news.ycombinator.com/

The translators also need to take on themselves a large part of the promotion in the language communities. Both in the Perl community - to get help from others - and to the general public.

This can be by posting on the language sub-Reddit (e.g. on http://www.reddit.com/r/Romania )

Sharing the articles on Google+, Twitter and Facebook should be almost automatic.

Getting the RSS feed of the site to be included in some local 'planets'.

SEO explained in 5 words

"Get links from trusted sources" ~ Jon Morrow

The best promotion is if people find it worth to mention one of the articles in a blog post or in some other form.

Git and Github

There is good and free book about Git called Git Pro http://git-scm.com/book

Install Git on you desktop configure username and password generate ssh key: https://help.github.com/articles/generating-ssh-keys

Create a Github account, let's say your username is USERNAME: Upload the ssh key to your account On Github 'fork' the https://github.com/szabgab/perlmaven.com repository It will create another repository https://github.com/USERNAME/perlmaven.com

clone it to your desktop:

$ git clone git@github.com:USERNAME/perlmaven.com.git

It will create a directory called perlmaven.com inside all the source files. There should be one called sites/CC (where CC is your language code based on this list: https://meta.wikimedia.org/wiki/List_of_Wikipedias more or less). If there is no such directory ask Gabor to create one.

Initially you will need to know about

$ git add  filename
$ git commit -m "message"
$ git push

And on Github there is a button to "Send Pull request" that will notify me to look at what you pushed, but of course I am also available by e-mail and GTalk.

To follow the changes in the central repository and keep your own fork up-to-date, do the following:

In your working copy do this once:

$ git remote add upstream git://github.com/szabgab/perlmaven.com.git

Then every time you'd like to sync:

$ git fetch upstream
$ git merge upstream/main

Github workflow for translator and reviewer

For some of the languages there are more than one translators, and they like to review their translations before pushing it out. This is a recommended workflow for them.

Let's say there are two people involved one has a username 'translator' the other one username 'reviewer' on Github

translator:

fork      https://github.com/szabgab/perlmaven.com
creating  https://github.com/translator/perlmaven.com

reviewer:

fork      https://github.com/szabgab/perlmaven.com
creating  https://github.com/reviewer/perlmaven.com

translator:

do the translation, put the file in the sites/CC/drafts/ folder and push it to Github

reviewer:

$ git remote add joe_the_translator git://github.com/translator/perlmaven.com.git
$ git fetch joe_the_translator
$ git merge joe_the_translator/main

Now the reviewer also has the file in her drafts/ folder locally The reviewer can make changes locally, commit them and push them to Github.

translator:

$ git remote add sally_the_reviewer git://github.com/reviewer/perlmaven.com.git
$ git fetch sally_the_reviewer
$ git merge sally_the_reviewer/main

Now the translator has the changes from the reviewer.

The fetch and merge parts can be repeated, the git remote add part only needs to be done once.

Once the translation is ready. The file can be moved from drafts/ to pages/ by either the translator or the reviewer:

$ git mv sites/CC/drafts/article.txt sites/CC/pages/article.txt

pushed it to Github and a merge request can be sent to Gabor.