survivejs/maintenance-book

”SurviveJS — Maintenance” book

SurviveJS - Maintenance

Maintaining web projects is difficult. The purpose of this book is help you to maintain your projects and gather good practices into a single place. You can read the book online.

How to Use This Repository?

You can read the content easily through the book site. It is also available within the manuscript directory of the repository.

The book is developed under the master branch. It contains the source of the most recent development version. Each version has been tagged so that it's easy for you to find the source matching to the version of the book you are reading.

Getting Support

As no book is perfect, you will likely come by issues and might have some questions related to the content. There are a couple of options to deal with this:

• Contact me through GitHub Issue Tracker
• Join me at Gitter Chat
• Follow @survivejs at Twitter for official news or poke me through @bebraw directly
• Send me email at [email protected]
• Ask me anything about webpack or React at SurviveJS AmA

If you post questions to Stack Overflow, tag them using survivejs so I will get notified of them. You can also use the hashtag #survivejs at Twitter.

Announcements

I announce SurviveJS related news through a couple of channels:

• Mailing list
• Twitter
• Blog RSS

Feel free to subscribe.

Contributing

Feedback and PRs are welcome! See CONTRIBUTING.md for more information.

License

maintenance-book's Issues

Discovering Explicit vs Implicit trade-offs

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"

Figure out a better subtitle

The current one feels too vague and doesn’t reflect the content accurately. I think we might need something more concrete here.

cover security

some thoughts(but it should be more):

• it is recommended to enable 2fa.
• npm audit

nsp has been deprecated

The Node Security Platform service is shutting down 9/30 - https://blog.npmjs.org/post/175511531085/the-node-security-platform-service-is-shutting

Continuous Integration chapter

Cover gh-lint

There's a stub in #42. It won't need much. A paragraph or two.

Cover GitHub Actions

I don't have much (okay, close to zero) experience with them, but looks like it's a good alternative to Travis.

Documentation part

• README chapter (automation, testing examples)
• Site chapter
• API Documentation chapter
• Linting chapter

Conclusion chapter for the book

This should recap the main ideas of the book.

Discuss GitHub teams?

This is related to the process topic and it becomes important as a project grows.

Explore Git message convention linting

There are likely good tools for a prepush hook or so to push message quality.

Cover Travis CI stages

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

Add a "code consistency" chapter

Code consistency is crucial for readability and maintainability:

• What is consistency? (is it the look of the code? is it the structure?)
• What isn't consistency? (e.g. does using class and function declarations cause inconsistency?)
• Why consistency matters
• How consistency can bring about better development practices

Consistency patterns:

• revealing module pattern
• more describe here

Processes chapter

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).

Cover npx?

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?

Cover CODEOWNERS

https://github.com/blog/2392-introducing-code-owners
https://help.github.com/articles/about-codeowners/

Research debugging

Local/remote debugging. Solutions like weinre. Out of scope?

Cover size-limit in detail

Maybe a small example.

Foreword for the book

We have to find and convince a maintenance expert to write a foreword for the book.

linting typescript using eslint

https://eslint.org/blog/2019/01/future-typescript-eslint

Feedback from Marc

• I think you should add one line to talk about the runner ups and deprecated alternatives to npm in the intro about packages. Component and Bower comes to mind. Also another sentence about stuff like jspm, duojs, yarn and pnpm wouldn't hurt.
• In the UMD chapter you could link to https://github.com/LeeCheneler/umd-generator
• You should link to keepachangelog in the changelog chapter.

Cover microbundle

https://github.com/developit/microbundle

Cover remark-lint

https://github.com/remarkjs/remark-lint
https://github.com/survivejs/maintenance-book/blob/master/.remarkrc

Linting JSON

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.

Code quality ideas

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?

References to lint-staged

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.

Consider different viewpoints

Two at least:

• Legacy vs. modern - If you do only a modern build, you can forget about standalone dist bundles and UMD (a big win)
• Maintainer vs. contributor vs. consumer views on different aspects.

Infrastructure / automation / bots

There are some ideas in the text already.

Cover changesets

I don't fully understand how it works, but it was recommended several times.

https://johno.com/changesets/

Packaging misses

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
• updating a package - breaking changes of a package, when not to update a package
• documenting your packages - (refer to documenting chapter)

[02]

• using comments inside JSON is a bit confusing, maybe needs reformatting?

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.

Chapter idea: TODO comments monitoring

• Tools like Leasot or imdone (not so sure about this one and what it does exactly :-).
• Why not to use no-warning-comments ESLint rule

Refactor bundling definition

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.

eslintrc do not support json5

https://github.com/survivejs/maintenance-book/blob/master/manuscript/code-quality/01-linting.md#eslint-configuration-formats

.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)

Split testing chapter

It's way to big and unfocussed now. Probably we could split it into:

• a quick overview of testing methods;
• examples that are the most useful of OSS.

Possible examples:

• Jest (expand or even replace the assert example);
• Cypress (maybe);
• size-limit;
• what else?

Infrastructure refactor & new section

Infrastructure's processes section needs a little bit of cleanup IMO, and possibly adding a new section, Coordination.

[01 - processes]

• Pull out Coordinating Teams
• Pull out Maintaining Project Focus

[04 - coordination]

• add Coordinationg Teams
• add Maintaining Project Focus
• add Team Collaboration? - Slack, Gitter

Thoughts?

Cover Danger

Cover npm ci

A new way to make CI faster by installing dependencies using only lock file.

https://medium.com/@tomastrajan/how-to-speed-up-continuous-integration-build-with-new-npm-ci-and-package-lock-json-7647f91751a

Documentation - API

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:

  • A bag of goodies;
  • everything you need is clicks away;
  • promotes growth to the library

• Cons:

  • Maintaining a separate piece of your codebase can mean possibly double the amount of work to add/remove a feature;
  • the time it takes is obnoxious;
  • larger-scale projects might find trouble in agreeing in API;
  • "API" can be an ambiguous term (see: google vs oracle 😄 )

Connect Prettier to the project

This should format everything.

.prettierrc

{
  "trailingComma": "es5",
  "printWidth": 68,
  "proseWrap": false
}

Cover sideEffects flag in package.json

https://twitter.com/wiekatz/status/1076112047866298368

More info re. inline unit testing

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.

Publishing types

Publishing types should be a separate chapter. You don’t have to use Flow/TS yourself to publish typings.

Spanish translation

I'll update this issue when a translation is relevant. Now it's too early (need to finalize the book).

CC @shadowz10.

Cover Mrm

Add more detail on npm scripts

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.

Linting and formatting CSS

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:

• How many rules does Prettier implement over CSS? Some are exposed via options, I guess there are others.
• Will Prettier support plugins, as Stylelint does (such as Order)? This strikes me as a very useful plugin which makes Stylelint worth using right away.
• Can Stylelint --fix all the rules that Stylefmt used to be able to do (thus rendering the latter definitely redundant)?
• Are there things that Prettier fixes in terms of formatting that Stylelint does not, thus making it worth using?

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?