Discussion: Baseline practices - brainstorm initial list

[Emuentes]

This issue is to discuss/brainstorm an initial set of best practices that the team would focus on.

To start the discussion there are some possibilities:

• Maintaining Modules:

  • Generally, effective access control / publishing rights on npm

    • for example use of 2 factor auth

  • How to transfer sole ownership of a module

    • how to establish trust of potential new owner
    • how to inform module users/ node community

  • How to request help, but not relinquish ownership

    • how to facilitate easy contribution from 'trusted' parties

  • Adherence to SemVer, adopting (some form of) module LTS, keeping dependencies minimal and up-to-date

  • What to do when it all goes wrong

    • Malicious takeover
    • Backing out malicious code contribution
    • Known severe vulnerabilities clearly being exploited, no time/ability to fix

• Consuming Modules:

  • Help assessing and including a module -- Content from this talk might be a good starting point https://www.youtube.com/watch?list=PL0CdgOSSGlBY7DBgOp1xsRvV31AAUZrX2&v=6pHuj6Hs9Gwfor distilling best practices

[rxmarbles]

Great starting point @Emuentes. I currently help maintain the react module react-dropzone one way i was able to become a maintainer was the main maintainer asking for help via an issue react-dropzone/react-dropzone#479. Of course this lead to many people asking to help, however not many were added. I believe a good way to see if you can add maintainers as contributors (who have access to admin perms of a repo) is by how often they contribute. Just a few thoughts 😄

[wesleytodd]

adopting (some form of) module LTS

https://github.com/CloudNativeJS/ModuleLTS

[Emuentes]

@rxmarbles Excellent point about "how to establish trust of potential new owner", their current OSS contributions or at least their own development activity can be an helpful indicator of their likeliness to participate actively.

In my current role I interview many people for few roles so I sometimes have to pick between many excellent candidates.

Questions to folks following this discussion:

1. What might be some other indicators we can use to carefully choose between viable candidates for ownership transfer? What would you hope to see in the person that will be keeping your dependencies going?

2. How would you want to receive notice about a change in ownership?
   Emails, change log on the repo, blog post somewhere, notification printed out during the NPM install, etc. Where would you be most likely to look for this information?

3. @rxmarbles and other maintainers, how do you request help with your modules without handing over admin rights?

4. to @wesleytodd's point, how do we validate help maintainers hold themselves accountable to sticking with SemVer?

Maybe we could recommend or create an npm module that asks the right questions to make sure that maintainers who may not be clear on how to manage their SemVer have help validating that they are bumping the version correctly considering the level of change they introduced and encourage folks to use it.

1. What issues might we introduce by adopting (some form of) module LTS

2. At what point do we have too many dependencies?

3. How often should we recommend that maintainers update their dependencies and is there a practical way to facilitate the process?

4. What would you suggest maintainers do when they find themselves with no time / ability to fix their projects?

5. What would you do or recommend for folks to do if they need to back out malicious code contributions?

[mhdawson]

@Emuentes good questions, we'll need to figure out next steps for answering those.

[mhdawson]

Additional potential baseline practices:

• Testing (was mentioned in another thread with respect to Travis CI)
• Security reporting (guidelines on how to take respond to reports? , we should work with security-wg to define, but practice itself probably belongs along with the rest of them)
• Support
  • Support statement? Would it be good for the module owner to indicate if its a "hobby" or related to
    some "paid" work?
  • As a consumer it would also be great to know if anybody provides commercial
    support.
  • LTS strategy as mentioned earlier
• Choosing a licence? -> This might be controversial
• Choosing dependencies

[mhdawson]

Wondering about this as the title for the end result: "Node module maintainer's handbook"

[mhdawson]

Thinking about "Support" I'm thinking that we'd want to say the baseline practice is to state the level of support provided, and to make this easier for maintainers by documenting a set of levels that they could choose from. Similar to how there are standard licences and maintainers can choose the licence they want to support versus having to write one from scratch.

An initial list might be:

• Not recommended for use, module is deprecated or no longer maintained
• Use at your own risk - no active support
• Maintained, latest Node.js version only upates
• LTS as outlined in https://github.com/CloudNativeJS/ModuleLTS
• Something beyond LTS where older non-LTS versions are supported as well

For each level it should outline how SemVer is used, and what level of support is available for each SemVer major stream.

Just like the licence it would be good to have this as part of the Package.json which would let tooling check for changes to the policies for dependent modules.

[mhdawson]

A key thing for each baseline practice we should keep in mind as we work on these is what do we do (document, provide tools, etc.) to help maintainers follow the baseline practice as opposed to stopping at defining the practice itself.

[mhdawson]

This issue #5 has some discussion around tooling that might be part of what we recommend to make baseline practices easier to follow. Also provides some insight into what baseline practices are already being used in practice.

[sympatheticmoose]

@Emuentes just my initial thoughts here - certainly not complete solutions, and apologies all for the massive post:

What might be some other indicators we can use to carefully choose between viable candidates for ownership transfer? What would you hope to see in the person that will be keeping your dependencies going?

I think track record is the main indicator here, you hand over to someone who has already taken on open issues, raised quality PRs or suggested improvements to the module itself. Failing that, a review of the other github contributions and whether others already 'trusted' can vouch for them

How would you want to receive notice about a change in ownership?
Emails, change log on the repo, blog post somewhere, notification printed out during the NPM install, etc. Where would you be most likely to look for this information?

The hope with this effort would be that a change in ownership shouldn't matter to the end consumer of a module. Ultimately I think our role here is more to advise module owners that they make their users aware using the channels that are effective for them. If they don't really have a huge user base or know how to reach their users - I agree with your suggestions, and we just say they should publicise intent initially (and 'please note' for a grace period afterwards) through an issue and readme header, update in the change log and potentially the npm install notification. In an ideal world could perhaps time handover with new major version release.

how do you request help with your modules without handing over admin rights?

Could this become part of our efforts? For modules essential to the ecosystem (this may be tricky to distinguish and could be unfair on smaller modules... but theres only so much time people have), they could raise an issue for security or critical fixes and members of this group could volunteer.

how do we validate help maintainers hold themselves accountable to sticking with SemVer?

I'm not sure we can (or perhaps even should) do much enforcing here, just advising the use of SemVer and highlighting its benefits. For those in the group in can kind of be a social contract... we could also suggest/enforce(?) code reviews. I like your idea of finding a way to ask the right questions when preparing a release.

What issues might we introduce by adopting (some form of) module LTS

None whatsoever ;) I say that as I'm a big fan of the idea. The one @wesleytodd has linked to was designed to be fairly simple to adopt assuming you're not burning through major versions - which generally is a pain for enterprise users anyway and probably means the module should still be 0.x.x. If you need to introduce breaking changes within public API, then it means you now have to maintain multiple release streams. That said, the only fixes that are required to be backported are security or critical (high severity/mass impact) - so the overhead in theory shouldn't be huge - I'm hoping as we're chatting to friendly maintainers we can further validate this.

At what point do we have too many dependencies?

Fair comment as this is tricky to quantify and is totally dependent on the complexity/intent of your module. My thinking here was more around if this group is trying to promote best practices - advising developers to be judicial in both which modules they use in apps/their own modules and how many.

How often should we recommend that maintainers update their dependencies and is there a practical way to facilitate the process?

When required ;) at least review when major versions change in dependencies, or when bumping your own modules major version, and act on security alerts. No idea on a way to facilitate.

What would you suggest maintainers do when they find themselves with no time / ability to fix their projects?

If short term, maybe the issue raising mechanism outlined above, longer term - onboard additional admins/handover. Neither likely to work - raise awareness in your user base the same ways outlined for changing owner.

What would you do or recommend for folks to do if they need to back out malicious code contributions?

Again i'd like to hear from those who've experienced this.

[sympatheticmoose]

@mhdawson

As a consumer it would also be great to know if anybody provides commercial support.

This is something that was started to be built out in modules.cloudnativejs.io (which could also help with the whole 'how to choose your module')

Choosing a licence? -> This might be controversial

Agreed. I think we could however just highlight potential choices and their positives/negatives without too much grief. Was there a particular reason you were thinking of this as a practice to call out?

[mhdawson]

@sympatheticmoose no particular reason, just covering the different areas where some baseline practices could apply. Licences and the licences of the dependencies are important to consumers.

[sympatheticmoose]

@mhdawson very much agreed - i was more thinking of that for the 'how to choose your module' aspect of this, rather than guidance to module owners though.

[ljharb]

(0.1 to 0.2 is a major version, ftr; being sub-1.0 doesnt signal anything different, it just makes your version numbers less immediately intuitive - I’d like one of our “best practices” to be “always start at v1”, which is also npm’s advice)

[sam-github]

being sub-1.0 doesnt signal anything different

This isn't correct: https://semver.org/#spec-item-4

The meaning of version numbers before 1.0.0 is undefined, the only requirement is not to reuse them (and well formedness). This is why npm, inc changed its advice to always start at 1.x. I think they should refuse to accept them being published if its the intial publish (so existing semver-invalid packages are allowed, but new ones can't be created).

Historically, npm packages were starting in the 0.x range until some nebulous "stable" status was achieved. Node was even using this invalid interpretation of semver in its 0.x range of releases, which it should not have done (in retrospect).

I’d like one of our “best practices” to be “always start at v1”, which is also npm’s advice

Absolutely agree. Any package that is published to npmjs.org is public by definition, and should be using versions with meanings defined by semver, and that means 1.0.0 or greater.

[ljharb]

That’s the latest version of the semver spec; i believe a previous one matched my interpretation. Not that important tho.

[vweevers]

Any package that is published to npmjs.org is public by definition, and should be using versions with meanings defined by semver, and that means 1.0.0 or greater.

I disagree. 0.x is a valuable signal. It says, "look, I'm playing around with an idea, I don't know what it will look like in the end, but if you wanna use it - at your own risk - that's totally cool." This ability to easily share rough ideas is fantastic. To experiment and to have fun, without the constraints of semver and worrying about breaking dependents (because again, in this stage, that's their risk).

[ljharb]

@vweevers that statement applies equally well to something at v1, or v57, or v0.x.

[vweevers]

that statement applies equally well to something at v1, or v57, or v0.x.

That might differ per person. For me it does not. It's not always obvious whether some change warrants a major. Prior to 1.x, you don't have to think about that, which frees up the mind. Note that I prefer the latest version of the semver spec (where meaning of 0.x is undefined).

[mhdawson]

In resepect to

The hope with this effort would be that a change in ownership shouldn't matter to the end consumer of a module. Ultimately I think our role here is more to advise module owners that they make their users aware using the channels that are effective for them. If they don't really have a huge user base or know how to reach their users - I agree with your suggestions, and we just say they should publicise intent initially (and 'please note' for a grace period afterwards) through an issue and readme header, update in the change log and potentially the npm install notification. In an ideal world could perhaps time handover with new major version release.

I agree that we should aim to provide guidance etc. to work towards the goal of it not mattering. On the other hand though I still think it could be useful to help surface the information so that consumers can decide do due diligence if they want to. For example, if I've reviewed the dependencies for an application and deploy an updated version there could be one of 2 cases: no change in module ownership -> nothing to do. Changes in ownership -> re-review. As a concrete example if I'm using a dependency from IBM I may just trust that license checks etc. have been completed. However, if its now being maintained by some other company I may want to take a closer look. We'd need to validate that consumers would find the info useful. There are also other issues in that I'm not sure "ownership" is that clearly defined in npm (there can be multiple maintainers) and no way that I know of that you could validate ownership claims if they were added to the package.json.

[mhdawson]

Thinking a bit more about "ownership" is really one part of the bigger picture of "trust", if there are other ways of gaining trust in a module then you might not need to worry about ownership but others ways of gaining trust are currently hard (manual review, etc.) and so ownership is one of the things people look at.

@sympatheticmoose re-reading what you said, in the end I don't think I added anything too different on reflection.

[rxmarbles]

I will take over summarizing the conversation and writing up actions that will be taken next.

[gentios]

Unfortunately I couldn't attend the yesterday's meeting, and I am waiting for the recording to be published, but regarding the first meeting and the discussions I have come up with the below points which I think should be considered as best practices:

• Maintainers wanted badge Process to identify and engage with "Key Packages" #105
  In order to find the packages that we would like to contribute and support, we should keep a list of the packages that are in need for maintainers and contributors. A good example is this GitHub repo: https://github.com/pickhardt/maintainers-wanted. A package that is in need for support should incorporate the badge in their repo.

• Security check on the modules that we are going to support
  We should work closely with the Security Working Group to give us a green flag on the packages that we are going to maintain. Some packages may have malicious code on them, we wouldn't want to support such packages.

• Background check and white list for package maintainers team
  Since this group is growing fast, we should do a background check and create a white list of the trusted members before allocating and incorporating in any package to be supported

• An on boarding documentation from the package owners Suggestion: Provide template/guides/automation for common maintainer needs #17
  A good documentation about the project structure, core logic, and contributing I think is very important since for example I have find it very hard to be contribute to a package or project without proper on boarding documentation, it is time consuming and frustrating.

• A package-maintainers badge

We should create a package-maintainers badge, and this badge should be incorporated in the packages that we are supporting. This would bring a reputation for our group and also a sign of trust for the end-users that are going to use that package, and also marketing of course.

[mhdawson]

@gentios I'd be interested in what a Background check might consist of. Would you be able to write up a first draft of what that process might be in the context of the package-maintenance team/initiative?

[gentios]

@mhdawson yes I will, write something initially that and I will share it.

[Eomm]

@gentios Could this protobot help maybe?

https://probot.github.io/apps/background-check/

[Emuentes]

I will take over summarizing the conversation and writing up actions that will be taken next.

@rxmarbles Let me know if I can assist you in any way with breaking the conversation down into smaller issues.

[mhdawson]

@gentios any chance you can create the summary before the upcoming meeting on Monday?

[mhdawson]

First draft of a baseline practice around documenting expected support: #139

[rxmarbles]

@Emuentes I appreciate the assistance. I have been a bit busy w/ work. I would be happy to split up the tasks with you on creating these summed up issues.

[gentios]

@Eomm thank you for the link, looks good as something initial

@mhdawson yes I will prepare everything before the meeting on Monday.

[rxmarbles]

Closing this as issues above have been opened to focus and continue discussions in relation to baseline practices. This will help flesh out these sections more to help with creating drafts for these parts.