Date::Holidays releases – adapter pattern at large

Since the post on the release 1.10 of Date::Holidays I have released:

1.11 Improved support for Date::Holidays::SK
1.12 Improved support for Date::Holidays::USFederal as US
1.13 Support for Date::Holidays::CA_ES, via Date::Holidays::ES
1.14 Marking of Date::Holidays::UK and Date::Holidays::UK::EnglandAndWales as unsupported, using Date::Holidays::GB instead
1.15 Improved support for Date::Holidays::DE
– and 1.16 Support for Date::Holidays::CZ

And I have more releases in the pipeline.

All of this work started out primarily as an attempt at getting to the bottom of the issue list, new issues do pop up as I get around the different corners and adaptations, but that is perfectly okay and I might never get to the bottom of the issue list, but at least the Date::Holidays distribution will improve and stabilise.

The work is also caused by a change in perspective, where my original motivation was to create a way to consolidate and use all of the different Date::Holidays::* distributions without having to adjust the differing interfaces of all of them.

I just spotted that my documentation lacks a section on motivation, describing the why of Date::Holidays – one more thing to the issue list.

The new perspective is that many of the distributions are not really being updated (which is a pity), but instead of creating a patch for the relevant distributions I am adjusting the adapters in Date::Holidays to implement the lacking features where possible instead of sending patches to the authors of respective distributions – I might do this afterwards, but since this will require a lot of effort, the other way around is faster and easier in most cases. Unfortunately there is also the chance that the original authors are unresponsive and my patches will never be released, so the strategy could be described as a “better safe than sorry” implementation.

About faster and easier, I am creating small tasks, which can be accomplished, while commuting. I have always been inspired by Ricardo Signes (GitHub), who I think have coded more commuting, than I have in front of my computer. This might be a slight exaggeration and Ricardo must correct me if I my description of this is out of proportion, at the same time there is nothing like a good programmer’s myth – well Ricardo is truly a prolific CPAN contributor and he does as such not require a myth.

Anyway – I am not a regular commuter and I will primarily be biking over the summer, so this will possibly not continue with this frequency, but I do enjoy bite-size tasks and I will try to squeeze them in when I can.

The whole change of perspective (and my reading of “Clean Code” by Robert C. Martin) has engaged me a lot and as I deal with all the practical issues I am also giving some thought to the bigger picture.

Date::Holidays have always and will always be a side project, once in a while I get contacted by somebody who use it or is trying it out and it makes me immensely happy, but I am not fooling myself – I do not think Date::Holidays has a big audience. I do get PRs with new implementations and that is awesome and I will keeping pushing for more integrations and adaptations, but it does not change the fact that the user base is limited.

So why do I keep coding on Date::Holidays?

Well, it is incredibly educational.

When I started out it was an exercise in the Adapter Pattern and it probably still is, but things have changed. Now I am reading “Clean Code” as mentioned and I am trying to adopt and learn some of the principles from that book.

Which leads me to the new road map for Date::Holidays, which is slowly taking shape.

– Adopt some “Clean Code” principles
– Factor out the “nocheck” flag (this is one of the principles)
– Factor out general features working on implicit country lists, this does simply not belong in the class (this might be one of the principles)
– Evaluate possible adoption of format parameter from Date::Holidays::* distributions
– Evaluate possible implement localisation of data from Date::Holidays::* distributions

So for now there will be a lot of smaller releases improving the actual adapters and at some point, I will look into making a major release, taking Date::Holidays to the next level, with a lot of clean code and hopefully I will be learning a lot during the proces.

Advertisements
Date::Holidays releases – adapter pattern at large

Release of Crypt::OpenSSL::X509 1.8.9

I have just released Crypt::OpenSSL::X509 1.8.9. Do note that this is not originally my distribution, but I have helped the author Dan Sully out a little since I am a user of his Crypt::OpenSSL::PKCS12 and Crypt::OpenSSL::X509 and I have an interest in the distributions continued existence, availability and functionality.

So this blog post is more a description of the proces of getting involved, using my involvement in Crypt::OpenSSL::X509 and it’s cousin Crypt::OpenSSL::X509 as examples.

I started out by making a few PRs for some issues we were experiencing, I slowly got involved as Dan not really maintaining the distributions so actively, not doing Perl and working on other stuff – all completely acceptable reasons. Dan started with giving me co-maintainership on PAUSE/CPAN, so I could upload releases. First release I made was simply from a fork, merging a PR post-release, not the best strategy, but it worked out.

Now I have commit privileges on both repositories and on PAUSE/CPAN I have co-maintainership so I can both implement and upload releases. Given this privilege is most certainly daunting and I am faced with a number of questions, some are easy to answer some are more difficult, some will not be answers at this time – anyway questions pop-up in your head:

  1. How much can I change?
    • Style?
    • Toolchain?
    • Functionality?
  2. Should I fix all the issues?
  3. Do I understand all aspects of the implementation?
  4. What if I cannot contribute?

Many answers will present themselves as you start to get more and more familiar with the project in question and other parts, over time, as you get more and more hands on. Currently I consider myself an apprentice in this context, everything is new, confusing and you are afraid to break something.
Modern software development is very forgiving, we have:

– version control and branching strategies
– continuous integration and unit-test suites
– collaboration platforms and open source
– and of course Google and StackOverflow

So it is very easy to get back to the original state, get feedback from either humans or machines or get help or find examples, which resemble what you are trying to accomplish.

Some of the PRs I had created enabled Travis integration for continuous integration, this was a contribution I could make without influencing the actual code – and easy one so to speak. Other PRs addressed issues the build tools. Both distributions are based on Module::Install, where all of my own distributions are based on Dist::Zilla, but for now it seems like at good idea to stick with what is already working, no need to change stuff just for the sake of change.

For coding style, I think it is a good idea to stick to the existing coding style of the project. When and if the project evolve even further, perhaps even on boarding more contributors or if PRs are getting difficult to review or understand it will perhaps be time to document a coding style or enforce a coding style.

Which brings me to the next point. Both Crypt::OpenSSL::X509 and Crypt::OpenSSL::PKCS12 are Perl implementations on top of a C-based library. For me this is a marvellous change to get to read some C-code, when reviewing PRs or familiarising myself with the project codebase.

Familiarising yourself with the existing codebase, can be also be accomplished by triaging bugs, the current bug count for the two project looks as follows;

– GitHub: Crypt::OpenSSL::X509 (17 issues)
– GitHub: Crypt::OpenSSL::PKCS12 (2 issues)

So there should be something to get me started.

In my opinion you do not have to fix all bugs, but it is a good way to dig in and learn a lot. Do not be hesitant to contact the bug reporter if you have questions, they might be long time users and have extensive knowledge of the projects inner workings. The same goes for contributors, which might even know even more since they have actually made a change and are requesting a merge.

What got me to release Crypt::OpenSSL::X509 1.8.9 was actually a PR, which I reviewed, it was in part of the code where I have proposed changes myself, so I would say I had an understanding of what was going on. The change however targeted an operating system, with which I am not familiar – so I wrote the contributor and asked, when there was something that was not clear to be. I got a marvellous response, point to some good documentation, so I learned something and I could complete my review.

Another strategy you can apply, or get anxious to start hacking away, is to add tests. Check the test coverage and implement more tests in the weak spots, that is also a good way to get into the functionality and composition of the project.

My advice is to just get started, review, read, code, learn, test… I do consider all that apprentice level, when you make your first release with a feature of your own or by request of some other, you are no longer an apprentice – you are a true contributor – and that is worth aiming for.

Good luck with your endeavours, there are plenty of projects to contribute to and there is nothing wrong with being an apprentice, all masters were apprentices once.

Release of Crypt::OpenSSL::X509 1.8.9

Date::Holidays 1.10 released

Release 1.08 of Date::Holidays had some issues with the test suite, which resulted in numerous failure reports from CPAN-testers, please see issue #21 for details.

This resulted in release 1.09, which addressed the problem with the bad tests. At the same time it however demonstrated issues with the integration towards Date::Holidays::NZ and Date::Holidays::SK, so issues #22 and #23 was created respectively.

Issue #22 has now been addressed in release 1.10 and next up is 1.11, which is planned to address issue #23 unless something else comes up.

The adaptation of Date::Holidays::NZ also supports the regional parameter described in: Date::Holidays::NZ.

So checking if New Years Day is a holiday in New Zealand, via Date::Holidays:

use Date::Holidays;

my $dh = Date::Holidays->new( countrycode => 'nz' );
if ($dh->is_holiday(year => 2018, month => 1, day => 1) {
        print “It is\n”;
}

And in particular for the region of Auckland (see Date::Holidays::NZ for details).

use Date::Holidays;

my $dh = Date::Holidays->new( countrycode => 'nz' );
if ($dh->is_holiday(year => 2018, month => 1, day => 1, region => 2) {
        print “In Auckland it is\n”;
}

You can also get a list of holidays:

use Date::Holidays;
use Data::Dumper;

my $dh = Date::Holidays->new( countrycode => 'nz' );

my $holidays_hashref = $dh->holidays(year => 2018);
print STDERR Dumper $holidays_hashref;

$VAR1 = {
    '0206' => 'Waitangi Day',
    '0402' => 'Easter Monday',
    '0102' => 'Day after New Years Day',
    '1022' => 'Labour Day',
    '1226' => 'Boxing Day',
    '1225' => 'Christmas Day',
    '0330' => 'Good Friday',
    '0425' => 'ANZAC Day',
    '0604' => 'Queens Birthday',
    '0101' => 'New Years Day'
};

And based on region:

use Date::Holidays;
use Data::Dumper;

my $dh = Date::Holidays->new( countrycode => 'nz' );

my $holidays_hashref = $dh->holidays(year => 2018, region => 2);
print STDERR Dumper $holidays_hashref;

$VAR1 = {
    '0129' => 'Auckland Anniversary Day',
    '1022' => 'Labour Day',
    '0101' => 'New Years Day',
    '0402' => 'Easter Monday',
    '1225' => 'Christmas Day',
    '0330' => 'Good Friday',
    '1226' => 'Boxing Day',
    '0102' => 'Day after New Years Day',
    '0425' => 'ANZAC Day',
    '0206' => 'Waitangi Day',
    '0604' => 'Queens Birthday'
};

Feedback most welcome,

jonasbn

Date::Holidays 1.10 released

Date::Holidays 1.08 released

I have just uploaded Date::Holidays 1.08 to PAUSE/CPAN.

It holds a new adapter class for Date::Holidays::USFederal (US) in response to a request from a user.

The implementation required a lot of changes to the internal code, due to the variation in the adapted Date::Holidays class name, Date::Holidays::USFederal, which is not an ISO compatible country code. I am pondering supporting this as US as well.

At the same time the test suite was restructured. I hope I did not break anything, all tests pass currently locally and with Travis via GitHub. I moved a lot of tests from *.t files into Test::Class based implementations, which I find much easier to work with.

Upon upload I did observe a failure in the indexing:

Status: Permission missing
 ==========================

module : Date::Holidays::Adapter::Local
 version: 1.08
 in file: lib/Date/Holidays/Adapter/Local.pm
 status : Not indexed because of case mismatch.

I am not sure what this error means, but I will investigate if this has raises any issues or give complications. The class was called Date::Holidays::Adapter::LOCAL earlier, so this might be the cause of the problem.

CPAN-testers are reporting a lot of failing tests, which I will also investigate (issue #21). I do not suspect the indexing issue to be related, currently I can see that this seems to be an issue with the include path (@INC) for the test classes in the distribution, but I have not been able to reproduce the issue with either prove, make test (based on Makefile.PL) or ./Build test (based on Build.PL).

Date::Holidays 1.08 released

Contributing to a new project – a bit like starting a new job

I have been using and creating open source software for a long time, I am however of the opinion that I never really have contributed anything of significance. Yes, bug reports, your occasional PR – are all important, but I have never ever contributed to anything where the project was high profile or it was a bigger project or system, with many contributors or an organisation behind it.

Recently I have been picking up from a lot of blog posts and podcasts that in order to evolve as a developer you have to get out of your comfort zone. I took the first step some time ago, when I decided to contribute to MarkdownTOC, a plugin for Sublime Text, where plugins are written in Python and my first contribution was the deletion of a single line. I do not program in Python, but I use Sublime Text and this particular issue, was scratching my own itch.

This was not much, but the positive impact was that the author actually welcomed my contribution and we started an ongoing collaboration. Since then I have contributed a lot more on the documentation side and currently I rank second in the number of lines contributed. Not that this is prestigious to me, but it does demonstrate that contributions even when not actual code are significant and are most appreciated.

At some point I fell over a tweet from EFF (The Electronic Frontier Foundation), indicating that their open source initiatives were looking for volunteers and contributors. After some consideration, I always do a lot of considering when about to leave my comfort zone, I decided to give it a go.

I can only speak for my self, but lets take a step back and reflect on comfort zone and open source and why contributing to open source is a comfort zone issue.

If we look at open source in general. You make something and you put it out there for other people to use or not use and it might be scrutinised or not. Luckily the amount of open source today is overwhelming, so you can actually open source your work and if people do not like it or do not want to use it, they pick another an alternative solution to the itch they need to scratch. This mean the scrutiny and feedback might not be as tough as it could be, I guess some open source authors work in areas where their contributions are being used and viewed by thousands of other people and scrutiny and feedback is different, the Linux kernel is an example.

I decided to have a look at the certbot project.

I do not program in Python, it is however an interpreted language and being a long time Perl programmer and based on my very limited knowledge on Python I did expect the two languages to have some familiarity.

After going over the issues labelled as “good first issue”, I decided on issue #4736. I commented on the issue, since I did not want to start working on an issue where somebody was already assigned or were progressing. I got a positive response and I was ready to get started.

Getting started required reading a lot of documentation on how to actually get started, how to contribute and what tools to use. Most open source projects are more than their source code. The have a lot of infrastructure integration and toolchain customisation, where some projects are “fork, hack, test, push”, you have to install additional tools and configure these.

I started by forking the project and got Sphinx up and running on my laptop.

$ pip install Sphinx
$ cd docs
$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
 Running Sphinx v1.6.2

making output directory...

Exception occurred:

  File "conf.py", line 133, in <module>
     import sphinx_rtd_theme
 ImportError: No module named sphinx_rtd_theme
 The full traceback has been saved in /var/folders/4s/v4_4270j5ybb60t4kjwk_f080000gn/T/sphinx-err-AmhKOS.log, if you want to report the issue to the developers.

Please also report this if it was a user error, so that a better error message can be provided next time.
 A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
 make: *** [html] Error 1

First problem was an easy fix:

$ pip install sphinx_rtd_theme
$ make html
sphinx-build -b html -d _build/doctrees   . _build/htmlRunning Sphinx v1.6.2

Extension error:

Could not import extension repoze.sphinx.autointerface (exception: No module named repoze.sphinx.autointerface)
 make: *** [html] Error 1

Second problem yet another easy fix:

$ pip install repoze.sphinx.autointerface
$ make html 

Finally reaching a success I was able to get started on filling in the blanks.

I scanned the file structure and compared it to the documentation structure.

cert_manager.py
 cli.py
 eff.py
 error_handler.py
 hooks.py
 lock.py
 log.py
 main.py
 notify.py
 ocsp.py
 renewal.py

plugins/
 common_test.py
 disco_test.py
 dns_common_lexicon_test.py
 dns_common_test.py
 dns_test_common.py
 dns_test_common_lexicon.py
 manual_test.py
 null.py
 null_test.py
 selection.py
 selection_test.py
 standalone_test.py
 util_test.py
 webroot_test.py

So I added the missing documentation files. When re-generating the documentation, the following issues were observed:

certbot/cli.py:docstring of certbot.cli.HelpfulArgumentParser.add:7: WARNING: Inline emphasis start-string without end-string.
 certbot/cli.py:docstring of certbot.cli.HelpfulArgumentParser.add:8: WARNING: Inline strong start-string without end-string.
 certbot/error_handler.py:docstring of certbot.error_handler.ErrorHandler:6: WARNING: Inline emphasis start-string without end-string.
 certbot/error_handler.py:docstring of certbot.error_handler.ErrorHandler:6: WARNING: Inline strong start-string without end-string.
 certbot/error_handler.py:docstring of certbot.error_handler.ErrorHandler:6: WARNING: Inline emphasis start-string without end-string.
 certbot/error_handler.py:docstring of certbot.error_handler.ErrorHandler:6: WARNING: Inline strong start-string without end-string.
 certbot/error_handler.py:docstring of certbot.error_handler.ErrorHandler.register:1: WARNING: Inline emphasis start-string without end-string.
 certbot/error_handler.py:docstring of certbot.error_handler.ErrorHandler.register:1: WARNING: Inline strong start-string without end-string.

A minor nifty trick helped eliminating the warnings. Finally I was left with warnings from Sphinx indicating some files not being part of the overall document tree structure.

certbot/docs/challenges.rst:: WARNING: document isn't included in any toctree
 certbot/docs/ciphers.rst:: WARNING: document isn't included in any toctree
 certbot/docs/man/certbot.rst:: WARNING: document isn't included in any toctree

After this I sent my first PR for issue #4736 all of these where just technical issues, which could be solved by myself. The overall job is far from done. Next step is getting the documentation up to date, meaning the information used by Sphinx to generate the documentation also has to be aligned with the actual implementation and I have just started on this. This does require more knowledge on certbot and more reading up on Python. My notes on Python details are growing as I cover more and more ground and until now and I have learned about.

– inner classes
– naming conventions
– module use and inheritance
– implicit returns
– the None datatype

I have many questions on the actual certbot implementation, but I will ask these with each assignment/file as I was recommended to make a PR per updated file and my first PR is slowly shaping up.

Starting contributing to a larger project is hard work, it reminds me of starting a new job, as you are exposed to: new systems, new tools, new processes and new colleagues. Much of what you do is similar or you have experience from previously, but at the same time everything is different, so no matter what there is a learning curve.

People on the certbot project are friendly and most helpful, this does mean that the issue with the comfort zone is alleviated. At the same time, if you focus on what you can bring to the project in question, the stuff you come with, even if this is just man hours, you cannot fail.

If however all of your PRs are declined, if all your questions are met with silence or all your inquiries are met with obnoxious responses – instead of feeling discomfort, find another project. There are plenty of other open source projects, which will welcome your efforts. And no matter what happens, you will have learned, you will have evolved – and you comfort zone will have grown. No need to be hindered by the comfort zone feeling, get out, there start small, contribute and evolve.

Contributing to a new project – a bit like starting a new job

Hacktoberfest 2017

Hacktoberfest 2017 is over.

This is the second year I participate. The event unfortunately collided with two conferences and a serious deadline at work, so I was not able to contribute as much as I would have liked to. I know this is only my second year, but it seems to be an emerging pattern, since I always seems incredibly busy around this time of year.

Anyway here is a list of my contributions.

Patch to Crypt::OpenSSL::PKCS12. We use this component at work. I did not expect this to count, but I created a PR in October, so it counted – yay! The Distribution author has not yet made a release, but I will contact him shortly to see if I can help getting this pushed out

Evaluating another component we use at work Class::Accessor, I found out this distribution had a small handful of issues. I went over these and decided to give it a shot. I contacted the author via the regular channels, which resulted in a bounced email. Luckily I know the author via twitter and we have common friends, so I got a working email address. After getting an accept I lifted all the proposed patches into GitHub PRs and addressed most of the issues, since all of them were minor also as PRs. This resulted in the first release in 8 years.

GitHub made some tweets about their Github Explore and much to my disappointment Perl was not listed as a featured topic, it was not defined as a topic. I decided to give it a go and after much investigation on what logo to use I could send a PR to the project.

Of the projects I had lined up, where I wanted to contribute but could not find the time I can mention:

– I would love to contribute some more to certbot, but I could not find the time, I will blog more on this later
– The Perl distribution Business::Tax::VAT::Validation, which we also use at work, I think the documentation could do with a brush up. I have talked to the author and he is okay with this, I just need to find the time

And then there is all my own stuff.

Hacktoberfest is great, since you are enticed to do some more open source, which mean you might get exposed to other projects and perhaps even technologies.

I will be contributing to open source continuously and I hope to be able to participate in Hacktoberfest in 2018.

Hacktoberfest 2017

Aloha Module::Info::File

“Aloha: Means hello and Ehh.. also goodbye” – Bighead

I have just processed some old PRs for Module::Info::File. A Perl distribution I created a long time ago. The module was implemented as a subclass of Module::Info, which I thought lacked some use-cases like basic file handling.

Actually the whole module concept came from a script named version.pl, which extracted basic meta data from Perl packages and Perl module files – this led me to Module::Info and to a solution of subclassing into Module::Info::File.

Anyway I got the PRs processed and got the whole thing working nicely. I had a look at the internals and was not satisfied, parsing version numbers in Perl components have always been interesting.

Based on a old note I had a look at Test::Version a module to test your version strings assuming it did something clever I had not thought of. It appeared that Test::Version was just based on Module::Metadata.

Module::Metadata looks quite impressive so I decided to pull out all the internals of Module::Info::File and implement new logic founded in Module::Metadata – *clickity* *click* – version 1.00 ready and after some testing and adjusting uploaded to PAUSE/CPAN.

The Module::Info::File distribution contains a test to check whether the superclass Module::Info would implement the same functionality, causing Module::Info::File to be obsolete – this just never happened.

Just out of curiosity I read up on Module::Info, which had had several releases, a new maintainer and new functionality, which should have caused the mentioned tests to fail.

I had a look at the documentation and fell over the following:

“Module loaded using new_from_file() won’t have this information in which case you can set it yourself.”

So I thought why not look into whether my code can be ported to the superclass, since I actually do that, I did it prior to 1.00 and I do with 1.00…

Looking around for a Github repository link I ended up in the issues/bug tool RT. Here RT:115147 stood out.

“I wonder if it is time to deprecate Module::Info, or at least point to Module::Metadata as the in-core and preferred mechanism for gathering module information? It looks like Module::Info’s mechanism for parsing $VERSIONs out of files is quite incomplete and outdated.”

I had just changed Module::Info::File to use Module::Metadata and going over the newer releases of Module::Info I located module_info a magnificent tool for replacing my own version.pl – except for the fact that it outputs the filename instead of the package name when providing it with a file as argument.

So now I am unsure of what way to go:

  • Should I deprecate Module::Info::File and just play along with Module::Info and it’s module_info
  • Should I talk to the current maintainer of Module::Info about using Module::Metadata internally so the file handling would improve, since I just observed that worked for Module::Info::File 1.00 and then deprecate Module::Info::File
  • Or should I just forget the whole  Module::Info / Module::Metadata thing and focus or maintaining Module::Info::File

Anyway it is all in the life-cycle of Perl distributions – distributions come and go…

Aloha Module::Info::File