survivejs / maintenance-book Goto Github PK
View Code? Open in Web Editor NEW”SurviveJS — Maintenance” book
Home Page: https://survivejs.com/maintenance/
”SurviveJS — Maintenance” book
Home Page: https://survivejs.com/maintenance/
To discover the trade-offs for Explicit and Implicit code, a "DIY" build system might be useful [but probably not].
Bash scripts
Rollup.js
Webpack/2
npm scripts
grunt? gulp? others?
pros/cons of having a robust vs minimal build system?
when introducing a build system might deem valid?
picking the "right tool for the job"
Maybe a small example.
A new way to make CI faster by installing dependencies using only lock file.
I notice that the code formatting chapter says lint-staged is discussed in the linting chapter then the linting chapter says it is discussed in the automation chapter.
https://www.npmjs.com/package/npx
https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b
Would it be valuable to cover npx somehow?
Code consistency is crucial for readability and maintainability:
class
and function
declarations cause inconsistency?)Consistency patterns:
.eslintrc
support some json5 features.(like single-quoted string, unquoted object keys). but it has been deprecated (https://eslint.org/docs/user-guide/configuring#configuration-file-formats)
In packaging/anatomy it would be good to see more information about npm scripts. For example, the way that start
, stop
and test
are shortcuts included which can be triggered without using run
whereas others must be preceded with run
. And the way that you can prefix any script with 'pre' or 'post' so that it's run before or after its main script. And whether there are any special implications to the main:sub
syntax.
I wondered if you guys have any recommendation of the best way currently to lint (and fix) JSON files - maybe this is worth mentioning. ESLint doesn't seem to do it, although there do seem to be plugins. I think Prettier supports it, but not via the eslint-plugin-prettier (which is how I'm using it).
Also re. JSON it might be worth recommending a config file format, as there are several to choose from, and saying why the JSON extension is the best choice, if it is.
There are some ideas in the text already.
Further to a chat with @bebraw I'm raising this as an issue here:
I was looking at this part of the book and I found myself wondering, if you wrote your code like this:
const assert = require('assert');
const add = (a, b) => a + b;
assert(add(1, 1) === 2);
module.exports = add;
That is to say, including testing code inside your modules instead of having tests separate and using a test runner, how would this affect the bundling and running of the app? At what point would the tests reveal themselves to either pass or fail? Maybe a little could be said about this.
This is related to the process topic and it becomes important as a project grows.
Publishing types should be a separate chapter. You don’t have to use Flow/TS yourself to publish typings.
some thoughts(but it should be more):
npm audit
This should recap the main ideas of the book.
I don't have much (okay, close to zero) experience with them, but looks like it's a good alternative to Travis.
There are likely good tools for a prepush
hook or so to push message quality.
There's a stub in #42. It won't need much. A paragraph or two.
The current one feels too vague and doesn’t reflect the content accurately. I think we might need something more concrete here.
This should format everything.
.prettierrc
{
"trailingComma": "es5",
"printWidth": 68,
"proseWrap": false
}
I like to use Most.js as an example of a complete API: https://github.com/cujojs/most/blob/master/docs/api.md
API documentation might cover:
Being one of the necessary documentation styles when having a modular codebase
Helping your users learn your code faster & being "developer friendly"
Massive code-bases such as stripe (also a great API)
tools for auto-generating API such as swagger (never used)
"OpenAPI" specification
Pros:
Cons:
Two at least:
Ok, I'll give the bundler definition another pass. Note that the concepts are visible in the newly added image too so you can see how the ideas relate to each other.
I'll update this issue when a translation is relevant. Now it's too early (need to finalize the book).
CC @shadowz10.
Here are some things I thought were missing from the packaging chapter:
[01]
npm view
- npm view [package] versions [--json]
// shows versions that you can install of a package[02]
Publishing and building might be able to benefit from adding some kind of follow-along or example? Just throwing that out there, I don't know how that could work.
A nice way to structure CI. Stages could be linting, unit tests, integration tests, coverage, automated release, etc. You'll have faster feedback (Travis will stop on the first failed stage) and you'll see exactly what's wrong with your build.
Example:
https://github.com/styleguidist/react-styleguidist/blob/master/.travis.yml
We have to find and convince a maintenance expert to write a foreword for the book.
The Node Security Platform service is shutting down 9/30 - https://blog.npmjs.org/post/175511531085/the-node-security-platform-service-is-shutting
Code quality, I want to say should have some layout like:
Modularity: writing code as standalone pieces towards a bigger puzzle
Naming: how to write good naming by following simple conventions
Consistency: consistent code is easier to read
"Cost factors"?: are you planing to expand your team? focus on readability and testability. planning on writing a proof-of-concept/side project? focus on the modularity so you can use your code later & aren't wasting your time when you write a side project.
"Cost factors" should stress that readability and testability being the desired use case
because sometimes modular code is just for sanity and only is useful if you plan to reuse or build upon the code. I'd say modularity is more of a best practice than a fundamental in regards to code quality, though it is important.
Thoughts?
Give this a pass and tweak where you feel it's necessary. Most likely it would be nice to discuss how it works with multiple people and different roles. That might use some image (I can draw if you do a rough one first).
It's way to big and unfocussed now. Probably we could split it into:
Possible examples:
assert
example);Maybe a bit more could be said about the current state of play between Stylelint, Stylefmt and Prettier when it comes to formatting CSS. I mean the case use for these tools - what makes one worth using alongside, or instead of, another. I have been trying to find out, for example:
--fix
all the rules that Stylefmt used to be able to do (thus rendering the latter definitely redundant)?Just as we can run Prettier for JS via ESLint, there is also a tool for running Prettier with Stylelint. It's a bit different though: apparently Prettier is run directly (Stylelint doesn't apply the formatting) then Stylelint is run. The tool just tries to match Prettier options with Stylelint rules.
Bottom line: what's the best workflow with these tools to take maximum advantage of linting and fixing, without redundancy?
Local/remote debugging. Solutions like weinre. Out of scope?
Infrastructure's processes section needs a little bit of cleanup IMO, and possibly adding a new section, Coordination.
[01 - processes]
Coordinating Teams
Maintaining Project Focus
[04 - coordination]
Coordinationg Teams
Maintaining Project Focus
Team Collaboration
? - Slack, GitterThoughts?
I don't fully understand how it works, but it was recommended several times.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.