On Mon, Dec 28, 2015 at 9:57 PM, Tim Landscheidt <[email protected]> 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 <[email protected]> [[m:User:BDavis_(WMF)]] Sr Software Engineer Boise, ID USA irc: bd808 v:415.839.6885 x6855 _______________________________________________ Labs-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/labs-l
