MattiSG
commented
9 years ago :+1: guidelines are very important. I'd advise putting them in a CONTRIBUTING.md file rather than README.md.
This has two advantages:
- Keep the user doc separate from contributor doc, avoid overloading README.
- GitHub will add a "Read the guidelines for contributing first" in any PR sent to this repo :)
Matti Schneider
Sent from a phone, please excuse the terseness.
Le 15 janv. 2015 à 14:14, sole notifications@github.com a écrit :
I'm thinking of adding these guidelines to the README as a new section so we are all on the same page. It's a way of formalising/dumping the knowledge we've acquired while tidying up the first two modules. Did I forget anything? @tofumatt @brittanystoroz
1) remove as many dependencies as possible and make the code super simple. Right now it is using underscore and Q and the code looks too cryptic unless you're familiar with those. So far using es6-promise and Promise.all has got me covered.
2) Try to be as obvious as possible. This means, for example, not using "B2G" if we can say "simulator" instead. Another example from this module: startB2G can be renamed to startSimulator and it is so much evident what it is doing for someone who is not familiar with the moz-jargon.
3) Only expose the API via promises. Granted you internally might need to use callbacks for other modules which are not promisified, but we want to make the whole API follow the same style, so once you learn to use one module, using another node-firefox- module is easy because the interface is the same: makeACall().then(doSomethingElse).
4) No CLI binary. None of the existing examples/use cases we came up with were using the CLI, so there's either no need for that or we hate the CLI. Either way there was a lot of duplicated code between modules for doing CLI and it wasn't too consistent, and we do not have too much time for this first iteration, so no CLI for now.
5) For naming, try to be as generic as possible but also as semantic as possible. For example, if a module can be used to discover firefox and firefox OS runtimes, try to avoid adding 'os' to its name, so that it is more generic. Also consider if something sounds weird, maybe it's because we're using the wrong name. E.g. fx-simulators sounded weird until it was renamed to find-simulators. When in doubt, discuss it with more people! Don't be afraid :D (specially if English is not your first language!)
— Reply to this email directly or view it on GitHub.
brittanydionigi
tofumatt
sole
I'm thinking of adding these guidelines to the README as a new section so we are all on the same page. It's a way of formalising/dumping the knowledge we've acquired while tidying up the first two modules. Did I forget anything? @tofumatt @brittanystoroz
1) remove as many dependencies as possible and make the code super simple. Right now it is using underscore and Q and the code looks too cryptic unless you're familiar with those. So far using es6-promise and Promise.all has got me covered.
2) Try to be as obvious as possible. This means, for example, not using "B2G" if we can say "simulator" instead. Another example from this module:
startB2Gcan be renamed tostartSimulatorand it is so much evident what it is doing for someone who is not familiar with the moz-jargon.3) Only expose the API via promises. Granted you internally might need to use callbacks for other modules which are not promisified, but we want to make the whole API follow the same style, so once you learn to use one module, using another node-firefox- module is easy because the interface is the same:
makeACall().then(doSomethingElse).4) No CLI binary. None of the existing examples/use cases we came up with were using the CLI, so there's either no need for that or we hate the CLI. Either way there was a lot of duplicated code between modules for doing CLI and it wasn't too consistent, and we do not have too much time for this first iteration, so no CLI for now.
5) For naming, try to be as generic as possible but also as semantic as possible. For example, if a module can be used to discover firefox and firefox OS runtimes, try to avoid adding 'os' to its name, so that it is more generic. Also consider if something sounds weird, maybe it's because we're using the wrong name. E.g.
fx-simulatorssounded weird until it was renamed tofind-simulators. When in doubt, discuss it with more people! Don't be afraid :D (specially if English is not your first language!)6) Use the build-tools module and gulpfile.js to lint the code.