Policy on private symbols

[Tristan Van Berkom <tristan vanberkom codethink co uk>]

Hi all,

Private and public symbols in the codebase have been a source of
confusion in the BuildStream code base for a while. I thought I had
something coherent when we started out, but it wasnt holding up and
inconsistencies keep creeping in.

As explained in the earlier:
https://gitlab.com/BuildStream/buildstream/merge_requests/150

And now:
https://gitlab.com/BuildStream/buildstream/issues/285

I have just now landed a refactor which improves this greatly, but I
still need to go through a lot of files with a fine tooth comb in order
to achieve consistency across the whole code base and ensure we remain
consistent and legible in the long term (usually a HACKING file is not
enough, people will always follow the style they find in the code they
are editing).

I have documented a (hopefully) clear policy in the HACKING.rst file,
which is now also a part of the documentation:

  http://buildstream.gitlab.io/buildstream/HACKING.html#policy-for-private-symbols

Which should now be followed in patch submissions and reviews.

Cheers,
    -Tristan