GitHub starts the Open Source Guides

GitHub blog is “Announcing Open Source Guides“:

we’re launching the Open Source Guides, a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to open source.

[…]

Open Source Guides are a series of short, approachable guides to help you participate more effectively in open source, whether it’s:

  • Finding users for your project
  • Making your first contribution
  • Managing large open source communities
  • Improving the workflow of your project

These guides aim to reflect the voice of the community and their years of wisdom and practice. We’ve focused on the topics we’ve heard about most, and curated stories from open source contributors across the web.

I think it’s a great idea and I really like the execution too.  Most of what I know about Open Source comes from years of participation, and from reading old books, manuals and licenses – not something that is easy to share with people who are just getting their feet wet.

GitHub’s Open Source Guides are very simple, concise and specific.  And they cover a variety of subjects, not just the legal or technical side of things, but also communications, support, marketing, etc.

Software Engineering at Google

Fergus Henderson, who has been a software engineer at Google for 10 years, published the PDF document entitled “Software Engineering at Google“, where he collects and describes key software engineering practices the company is using.

It covers the following:

  • software development – version control, build system, code review, testing, bug tracking, programming languages, debugging and profiling tools, release engineering, launch approval, post-mortems, and frequent rewrites.
  • project management – 20% time, objectives and key results (OKRs), project approval, and corporate reorganizations.
  • people management – roles, facilities, training, transfers, performance appraisal and rewards.

Some of these practices are widely known, some not so much.  There are not a lot of details, but the overall summaries should provide enough food for thought for anyone who works in the software development company or is involved in management.

 

pds/skeleton is now stable

PHP Package Development Standard, aka pds/skeleton, is now stable.  I’ve linked to it before and I think it’s a great idea and I’m glad I’m not alone:

Roughly 78,000 packages already comply with the pds/skeleton standard, although they may not know it. To formally show that your package has adopted the standard, “require-dev” it via Composer, or display a badge on your README.

I’d gladly follow this standard for my own work too, except that I mostly work with WordPress and CakePHP these days, both of which do things differently from the standard and from each other.

WordPress kind of assumes that the whole project is public, so you don’t really get public/ folder.  It also organizes the code into wp-includes/, wp-admin/ and wp-content/ folders, instead of the src/ suggested by PDS.  And, in terms of configuration, everything goes into wp-config.php file instead of something in the config/ folder.

CakePHP is much closer to PDS in terms of organization of files.  The only difference that I can spot is the use of webroot/ folder instead of the suggested public/.

I’d really love to see larger libraries and frameworks adhere to the PDS, but until that happens, I’ll keep an eye on things.

P.S.: The standards comic strip is of course from xkcd.

Defensive BASH Programming

If you write any Bash code that lasts more than a day, you should definitely read “Defensive BASH Programming” and follow the advice, if you haven’t already.  It covers the following:

  • Immutable global variables
  • Everything is local
  • main()
  • Everything is a function
  • Debugging functions
  • Code clarity
  • Each line does just one thing
  • Printing usage
  • Command line arguments
  • Unit Testing

All that with code examples and explanation of importance.

 

PagerDuty Incident Response Documentation

PagerDuty shares their Incident Response Documentation:

This documentation covers parts of the PagerDuty Incident Response process. It is a cut-down version of our internal documentation, used at PagerDuty for any major incidents, and to prepare new employees for on-call responsibilities. It provides information not only on preparing for an incident, but also what to do during and after. It is intended to be used by on-call practitioners and those involved in an operational incident response process (or those wishing to enact a formal incident response process).

I think this is a goldmine for anybody involved with incident response teams, operations, monitoring, technical support, network centers, and other similar setups.  Not only it covers the specific steps and expectations during different situations, but it also defines the culture, which the company is trying to built.

I wish I had this 15 years ago when I was involved in setting up the Network Operations Center (NOC).  I will definitely use it in the near future, when we’ll be setting up the support department at work.

Sharing constants between PHP classes

When writing larger applications, it is often useful to have some constants defined, which can then be shared between different parts of the application.  There are several ways to do this, and there is no real rocket science here.

However, the question is: what’s the best way to do so?

Until now I haven’t seen an elegant solution to this problem.  The old school way was defining the constants in the separate include file or in a class, and then accessing them through the global scope or via a specific class.  With a moderately modern PHP version, class constants can also be redefined by an inheriting class, which is, I think, more useful than painful.

Today, I came across an implementation that I really liked.  It’s simple and elegant: define constants in the interface and let classes implement it.  I saw it in the HTTP Message Util library, which defines HTTP methods, status codes and the like for the libraries and applications implementing PSR-7 standard (HTTP message interface).  Look here, for example.

I played around for a few minutes with this and it worked really well.  Until I stumbled upon something.  PHP classes can override the constants from the classes they inherit.  But not from the interface.  Here’s what PHP manual on Object Interfaces has to say about that:

It’s possible for interfaces to have constants. Interface constants works exactly like class constants except they cannot be overridden by a class/interface that inherits them.

This seems reasonable.  After all, the interface is a contract, and whatever is part of it should be precisely so in the implementing classes.  If you try to redefine the constants in the class:

<?php
interface FooInterface
{
    const FOO = 1;
}

class Foo implements FooInterface
{
    const FOO = 1;
}

echo "Foo = " . Foo::FOO . "\n";

you get an error:

PHP Fatal error: Cannot inherit previously-inherited or override constant FOO from interface FooInterface in foo.php on line 7

That sounds about right.  But!  It looks like you can overwrite the interface constants by extending the class.  The following snippet happily prints out two and throws no errors or warnings (my Fedora 25 runs PHP 7.0.14, if you were wondering):

<?php
interface FooInterface
{
    const FOO = 1;
}

class Foo implements FooInterface
{
}
class Bar extends Foo
{
    const FOO = 2;
}

echo "Foo = " . Bar::FOO . "\n";

Weird, right?  But there is more.  If the extending class implements the interface, rather than inherit its implementation from the parent, then the error is back:

<?php
interface FooInterface
{
    const FOO = 1;
}

class Foo implements FooInterface
{
}
class Bar extends Foo implements FooInterface
{
    const FOO = 2;
}

echo "Foo = " . Bar::FOO . "\n";

results in the familiar error, with the adjusted line number:

PHP Fatal error: Cannot inherit previously-inherited or override constant FOO from interface FooInterface in foo.php on line 10

Additionally, PHP provides the final keyword, which can be used to prevent overwriting of the inherited method by the child classes.  However, final keyword is not allowed on the constants, which makes results a bit more difficult to predict.  Especially so with the late static binding.  Here is an example:

<?php
interface FooInterface
{
    const FOO = 1;

    public function hello();
}

class Foo implements FooInterface
{
    public function hello()
    {   
        echo __FUNCTION__ . ": Self " . self::FOO . "\n";
        echo __FUNCTION__ . ": Static " . static::FOO . "\n";
    }   

    final public function bye()
    {   
        echo __FUNCTION__ . ": Self " . self::FOO . "\n";
        echo __FUNCTION__ . ": Static " . static::FOO . "\n";
    }   
}
class Bar extends Foo 
{
    const FOO = 2;
}

echo "\nFrom Foo\n";
$foo = new Foo();
$foo->hello();
$foo->bye();

echo "\nFrom Bar\n";
$bar = new Bar();
$bar->hello();
$bar->bye();

Which results in:


From Foo
hello: Self 1
hello: Static 1
bye: Self 1
bye: Static 1

From Bar
hello: Self 1
hello: Static 2
bye: Self 1
bye: Static 2

I can’t say for sure whether overwriting interface constants in inherited classes is a bug or not, but the current behavior does feel weird.

10 things to avoid in Docker containers

10 things to avoid in Docker containers provides a handy reminder of what NOT to do when building Docker containers.  Read the full article for details and explanations.  For a brief summary, here are the 10 things:

  1. Don’t store data in containers
  2. Don’t ship your application in two pieces
  3. Don’t create large images
  4. Don’t use a single layer image
  5. Don’t create images from running containers
  6. Don’t use only the “latest” tag
  7. Don’t run more than one process in a single container
  8. Don’t store credentials in the image. Use environment variables
  9. Don’t run processes as a root user
  10. Don’t rely on IP addresses

JSON API? No … HAL!

Wait, what?  That’s exactly what I said when I read this blog post.  I am still making my way through the JSON API specification.  And now it seems I might be wasting my time, as I should be learning HAL.

Whereas JSON API is almost like an “ORM over HTTP”, HAL does a lot less for you though, so it’s not really an apples-to-apples type of comparison.

HAL really is just a document format for a hypermedia API, like HTML is for hypertext. It doesn’t tell you how to express your domain model, and doesn’t really tell you how to use HAL to submit changes.

Sometime I think that I should just stop learning.  What’s the point?  By the time you learn a thing or two, it’s already obsolete and somebody somewhere has created something better, or wiser, or cheaper.

Meh…

PHP Package Development Standards

Paul M. Jones announces the availability of PHP Package Development Standards for review:

This initiative researches the PHP package ecosystem to recognize commonly adopted development practices. It rationalizes and refines those practices, then publishes them as PDS packages for reference by PHP package authors.

PDS publications are derived from and supported by common practices existing in real packages, as adopted by existing authors who have a continuing interest in the quality and consistency of their own work.

Have a look at php-pds/skeleton GitHub repository.

Personally, I welcome this initiative.  PHP ecosystem exploded in the recent years with the help of composer and Packagist.org.  There are over 120,000 packages just on the Packagist.org.  I think, it’s good to have some standards and best practices.  The PHP Framework Interop Group (PHP-FIG) is doing its best with the PHP Standards Recommendations (PSRs).  But we could have some more guidelines in order to have some consistency.

PHP Package Development Standards takes, in my opinion, the right way of looking at what’s out there, what works and what doesn’t, and than setting the guidelines based on the real world practices.  They cover things like file and directory naming conventions, versioning, changelog and licensing – which are common issues for pretty much every package.

Looking at the packages that I am involved with, only a few minor changes are necessary to comply.  Mostly, the “config” folder instead of the Unix-style “etc“, CONTRIBUTING file, and a CHANGELOG file, which I’m still to find a good way to semi-automate.