Operation Sundance: Fix everything else that is not code

[Staś Małolepszy]

L20n got a lot of positive ccomments after the talk at Front Trends
last week and I would like to take this opportunity to fix gaps in our
dev process that may be stopping developers from 1) using L20n and 2)
improving it.

With no documentation and few working tests, we create barriers to
entry for third-party developers instead of lowering them.

Operation "Sundance" is the codename of an effort to make L20n a mature
piece of software before we announce the 1.0 release.

The goal is to help third-party developers start getting to know L20n,
both when they want to play with it in their projects, and when they
want to hack on L20n itself.

I propose that only blocking-sundance+ bugs can land on master from now
on. These are bugs from the list below, as well as bugs that
completely stop L20n from working.


Process

- create the blocking-sundance[?-+] flag
- make master the stable branch after all of this is done
- create the unstable 'develop' branch?

Code

- Use AMD to modularize the code
https://bugzilla.mozilla.org/show_bug.cgi?id=805163
- Add License headers to all files
https://bugzilla.mozilla.org/show_bug.cgi?id=866618
- Add docstrings with parameters specifications to all functions
- Create and publish the annotated version of the code that uses docco
to extract comments and docstrings

Tests

- write/choose a test node.js runner (mocha?) and add targets in
Makefile and package.json
- unit testings: create meaningful tests for each of the modules; make
them runnable with the node.js runner
- integration testing in node.js: create a few full-blown tests for
different use cases
- integration testing in the browser: create a few full-blown tests
for different use cases that work in the browser
- CI: connect travis/jenkins to the github repo
- enable the CI bit on irc
- remove lol-fixtures

Build

- put builds targets in the Makefile
- write scripts to maintain the l20n.min.js repo
- publish l20n at npmjs.org

Documentation

- document a quick-start for developers: let the see a result quickly
(sandbox style?)
- finish L20n by Example
https://bugzilla.mozilla.org/show_bug.cgi?id=800573
- docs/tutorial for developers
https://bugzilla.mozilla.org/show_bug.cgi?id=802864
- document how to run and write tests
https://bugzilla.mozilla.org/show_bug.cgi?id=802870

Tools

- add the parsed AST view to the tinker
- create a code highlight plugin for vim

Go to https://l20n.etherpad.mozilla.org/operation-sundance to help me
make the above list complete.

-stas

--
Staś Małolepszy

[Axel Hecht]

How does that relate to the 30 bugs that I find via

https://bugzilla.mozilla.org/buglist.cgi?list_id=6445902&resolution=---&query_format=advanced&product=L20n&target_milestone=1.0&target_milestone=1.0%20beta

I'm a bit concerned that a new flag is going to make you spend time on a
new triage, instead of getting the blocker list down.

Axel

[Staś Małolepszy]

Quoting Axel Hecht (2013-05-02 16:01:46)

> How does that relate to the 30 bugs that I find via
>
> https://bugzilla.mozilla.org/buglist.cgi?list_id=6445902&resolution=---&query_fo
> rmat=advanced&product=L20n&target_milestone=1.0&target_milestone=1.0%20beta
>
> I'm a bit concerned that a new flag is going to make you spend time on a
> new triage, instead of getting the blocker list down.

You're right. Let's keep this simple and target 1.0 with all these
bugs. There's no need for another flag.

I updated the etherpad.

Axel, what are your thoughts on master vs. develop branches, given your
experience from Elmo?

-stas

--
Staś Małolepszy
+48 883 117 111
+1 650 933 7757

[Axel Hecht]

For releasing every other week, it's working good.

For l20n, I'd expect releases only every other month, and I'd expect
those to be proper release branches rather than merges of develop onto
master.

Axel

[Staś Małolepszy]

Quoting Axel Hecht (2013-05-06 11:38:30)

> For l20n, I'd expect releases only every other month, and I'd expect
> those to be proper release branches rather than merges of develop
> onto master.

Yeah, I was thinking along the same lines. Ideally, I'd like to see
one release per quarter.

-stas

--
Staś Małolepszy

[Staś Małolepszy]

Somewhat related to Operation Sundance is this post published on Hacks
today:

https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/

--
@stas

[Staś Małolepszy]

Quoting Staś Małolepszy (2013-05-01 23:38:03)

> With no documentation and few working tests, we create barriers to
> entry for third-party developers instead of lowering them.
>
> Operation "Sundance" is the codename of an effort to make L20n a mature
> piece of software before we announce the 1.0 release.

I'd like to give a quick status update about what we've achieved over
the last month and a half in terms of Operation Sundance.

>
> Process

>
> - make master the stable branch after all of this is done
> - create the unstable 'develop' branch?

Not done yet, but I started to think about this. I'l send out another
email about it.

> Code
>
> - Use AMD to modularize the code
> https://bugzilla.mozilla.org/show_bug.cgi?id=805163

Fixed. We use require.js in development on the client side, and node's
require (via amdefine) on the server side. We also use dryice to build
a single-file version of L20n for the browser.

> - Add License headers to all files
> https://bugzilla.mozilla.org/show_bug.cgi?id=866618

Fixed. L20n is now licensed under the terms of the Apache License,
Version 2.0. All relevant files have been updated to reflect that.

> - Add docstrings with parameters specifications to all functions

Not started yet.

> - Create and publish the annotated version of the code that uses
> docco to extract comments and docstrings

In progress. You can `make docs` to create the annotated HTML in
dist/docs, but it's not published anywhere yet.

> Tests
>
> - write/choose a test node.js runner (mocha?) and add targets in
> Makefile and package.json

Fixed in https://bugzilla.mozilla.org/show_bug.cgi?id=880727. I also
created some documentation about it:

https://developer.mozilla.org/en-US/docs/L20n/Contribute#Running_tests
https://developer.mozilla.org/en-US/docs/L20n/Makefile

> - unit testings: create meaningful tests for each of the modules; make
> them runnable with the node.js runner
> - integration testing in node.js: create a few full-blown tests for
> different use cases

In progress. We're only getting started on this.

Unit tests:
https://github.com/l20n/l20n.js/tree/master/tests/lib

Integration tests:
https://github.com/l20n/l20n.js/tree/master/tests/integration

> - integration testing in the browser: create a few full-blown tests
> for different use cases that work in the browser

Not started yet.

> - CI: connect travis/jenkins to the github repo

Fixed in https://bugzilla.mozilla.org/show_bug.cgi?id=881704. Builds
can be found here:

https://travis-ci.org/l20n/l20n.js

> - enable the CI bit on irc

I tried making Travis report build in #l20n, but I failed.

> - remove lol-fixtures

Not done yet. I first want to port all old compiler and context tests.

> Build
>
> - put builds targets in the Makefile

Fixed as part of the test runner update:
https://bugzilla.mozilla.org/show_bug.cgi?id=880727.

> - write scripts to maintain the l20n.min.js repo

Not done yet. I do this manually for now by symlinking the l20n.min.js
repo in dist/html.

> - publish l20n at npmjs.org

Fixed. https://npmjs.org/package/l20n

> Documentation
>
> - document a quick-start for developers: let the see a result quickly
> (sandbox style?)

Not started yet.

> - finish L20n by Example
> https://bugzilla.mozilla.org/show_bug.cgi?id=800573

In progress. 6 chapters remain.

> - docs/tutorial for developers
> https://bugzilla.mozilla.org/show_bug.cgi?id=802864

Not started yet. The bindings' README provides some basic information,
but it isn't a tutorial:

https://github.com/l20n/l20n.js/blob/master/bindings/README.md

> - document how to run and write tests
> https://bugzilla.mozilla.org/show_bug.cgi?id=802870

Fixed, see above.

> Tools
>
> - add the parsed AST view to the tinker

Not started yet.

> - create a code highlight plugin for vim

Not started yet.

--
@stas