[Labs-l] Some suggestions if you have no resolutions for 2016 yet

Thu Dec 31 00:32:09 UTC 2015

On Mon, Dec 28, 2015 at 9:57 PM, Tim Landscheidt <tim at tim-landscheidt.de> wrote:
> Hi,
>
> the new year is just around the corner and you still have no
> idea what to do with it?  Here are some suggestions for tool
> developers and maintainers:

This whole list of ideas makes me super happy.

> - Increase the [[bus factor]].  Add another (slightly inter-
>   ested) developer to your tool.  This does not mean that
>   they need to master the code from day #1, but that there
>   is someone who feels authorised/obligated to fix a bug
>   when you are on holiday/lost your password/have other com-
>   mitments/etc.  Do not wait for their written request; ap-
>   proach someone on your own.

This might be the most important and useful advice in a list of great
ideas. In The Cathedral and the Bazaar [0], ESR [1] notes that "When
you lose interest in a program, your last duty to it is to hand it off
to a competent successor." The easiest and best way to do that is to
create a community that is interested and active in your project long
before you lose interest. Its also a great way to bring new ideas and
experiences into your project to make it better. (Note ESR has also
said a lot of things that I don't agree with. Please don't choose him
as your personal role model for all interactions.)

> - Publish the source.  All of it.  Publicly.  Make sure that
>   there are no passwords in it.

There are a large number of options for this. Getting a repository on
the Wikimedia servers with Gerrit integration is as easy as filling
out a form [2]. There are obviously also free (gratis) hosting
solutions such as GitHub, BitBucket, GitLab, and many others [3]. We
are looking into creating even easier methods of creating and managing
git repositories on the Wikimedia infrastructure too to go with new
Labs services that are under development [4].

> - Write or review instructions on how to deploy your tool
>   from the source.  Do you just need to copy the source to a
>   directory?  Write it down.  Do you need to compile some-
>   thing, convert data from this format to that, download
>   stuff from here to there?  Write it down.  Who has a
>   backup of the bot's wiki account's password?  Write it
>   down.  This is not to guard against a Labs meltdown, but
>   your memory loss.  It may be totally obvious to you /now/
>   that you need to copy source repository A to directory X
>   and B to Y, but in a year's time you will likely have no
>   clue if the branch "new" or "bug-fix" is the correct one.
>   Ask your newly-found co-maintainers if they understand the
>   instructions.

This is a great thing to put right in the version control system you
pick to manage your code and maybe even automate a bit. I bet there
are some great home grown deployment tools and scripts in our current
developer community. Maybe some people would be willing to share what
they do?

> - Fix your tool's warnings and errors.  All of them.  Your
>   tool might still work if it encounters "undefined" or
>   "uninitialized" variables, but a) these warnings slowly
>   but surely fill up the storage space and (more impor-
>   tantly) b) if in a year's time you or tomorrow your newly-
>   found co-maintainer want (or rather need) to fix a bug,
>   you will not know if those warnings are just background
>   noise or indicators of a major malfunction.  If you want
>   to output "" if a variable is not set or something simi-
>   lar, don't use $variable and rely on PHP/Perl/etc.'s de-
>   fault behaviour and your brain to remember that, don't
>   write a comment in the code that the maintainer should ig-
>   nore the warning, write code that just does not produce
>   the warning.  It might take you a few seconds more to
>   write "isset($variable) ? $variable : ''", but will save
>   you much more time in the long run.  As a rule of thumb,
>   your tool's error.log should not grow in normal opera-
>   tions.  Ever.

This is something all projects large and small struggle with, but
whittling away at the noise in your logs is always valuable. As Tim
notes this is especially useful when adding new maintainers. I'd add
that when you purposefully emit log messages to alert yourself and
others to runtime errors try to make sure that the messages give you
enough context to figure out what went wrong even if the reader of the
log is only slightly familiar with the code and squinting at the error
message in the early morning.

> - Advertise your tool.  You developed it to do X, so write a
>   blog/village pump post demonstrating how you (or someone
>   else) do X easier/faster/at all/etc. so that others can do
>   X easier/faster/at all/etc. as well.  Users are great for
>   debugging because they do things with your tool you didn't
>   even dream of.  Or they have a suggestion on how to do X
>   even easier/fastier.  Or they are interested in the soft-
>   ware and you get a new co-maintainer without much of a
>   search.

I think we should carve out a space on wikitech for Tools to be
documented to make this easier. Should we create a new namespace
(Tools?) that is analogous to the Extension namespace on mediawiki.org
to do this?

Here's an additional idea that came to mind for me after reading Tim's list:

- Help someone else. Spend some time hanging out on the
#wikimedia-labs freenode IRC channel and answer questions that come up
if you can. Respond nicely to people who are looking for help and
point them to documentation or help them debug their issues.
Participate in this mailing list in the same spirit. Make the
documentation on wikitech better! File bugs in Phabricator. Submit a
patch upstream to some tool or library that you use which almost works
right. Take a look at the technical requests section of your favorite
wiki community and help people there. Go to a hackathon and spend part
of your time explaining how Labs, Tool Labs, your tools and/or your
favorite libraries work.

[0]: https://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar
[1]: https://en.wikipedia.org/wiki/Eric_S._Raymond
[2]: https://www.mediawiki.org/wiki/Gerrit/New_repositories
[3]: https://git.wiki.kernel.org/index.php/GitHosting
[4]: https://phabricator.wikimedia.org/T117071

Bryan
-- 
Bryan Davis              Wikimedia Foundation    <bd808 at wikimedia.org>
[[m:User:BDavis_(WMF)]]  Sr Software Engineer            Boise, ID USA
irc: bd808                                        v:415.839.6885 x6855