Update JavaScript community guidelines

[daviddias]

• Make sure it is up to date and that it incorporate the last week's discussion notes

@RichardLitt tagging you as you volunteered

[RichardLitt]

SGTM.

[daviddias]

Could you provide an ETA? I believe this is going to be super valuable to kick off the quarter :)

[RichardLitt]

@diasdavid Tomorrow? Whenever this is merged? :)

[daviddias]

List of things to be done:

• Merge https://github.com/ipfs/community/blob/master/js-commit-guidelines.md and https://github.com/ipfs/community/blob/master/js-project-guidelines.md to a single document
• List out every package in js-ipfs and js-libp2p main repo that those modules use (created by us) and add a column with their main Captain
• Add a section how modules should provide docs with jsdoc (referencing the awesome documentation endeavour)
• https://github.com/ipfs/community/blob/master/js-project-guidelines.md#linting--code-style should explain that aegir-lint checks for all the linting
• https://github.com/ipfs/community/blob/master/js-project-guidelines.md#building is completely out of date
• It would be great to have a section for the badges that we always put in every repo
• There should be no dependencies that rely in commits, instead there should be WIP PR and each PR that depends in other WIP PR should list what it depends too and yes, everyone will have to do the extra work of npm link everything, but that is what avoids most problems
• Have a clause that every module below 1.0.0 should use~ instead of ^. Submit PR to change all of these in all the modules
• update the .*ignore examples https://github.com/ipfs/community/blob/master/js-project-guidelines.md#gitignore
• merge this PR https://github.com/ipfs/community/pull/226/files

[RichardLitt]

List out every package in js-ipfs and js-libp2p main repo that those modules use (created by us) and add a column with their main Captain

Which modules? Can we use project-repos for this?

[RichardLitt]

• Add a section how modules should provide docs with jsdoc (referencing the awesome documentation endeavour)
• https://github.com/ipfs/community/blob/master/js-project-guidelines.md#linting--code-style should explain that aegir-lint checks for all the linting
• https://github.com/ipfs/community/blob/master/js-project-guidelines.md#building is completely out of date

@dignifiedquire Can you help with this? I think you'd be the best at it.

@diasdavid:

There should be no dependencies that rely in commits, instead there should be WIP PR and each PR that depends in other WIP PR should list what it depends too and yes, everyone will have to do the extra work of npm link everything, but that is what avoids most problems
Have a clause that every module below 1.0.0 should use~ instead of ^. Submit PR to change all of these in all the modules
update the .*ignore examples https://github.com/ipfs/community/blob/master/js-project-guidelines.md#gitignore

Can you please point to where these decisions were made? They seem extemporaneous to me.

[daviddias]

Apologies if it wasn't clear enough, @dignifiedquire @haadcode @victorbjelkholm could you confirm with what you understood? Sad that we didn't take digital collaborative notes.

I remember describing the problem (3 times at least) during the discussions of 2 weeks ago and also described how we, within the js-ipfs and js-libp2p development, solve it, which is what I'm describing in that paragraph. At the time of the group focused discussion (in person), I asked if everyone understand the issue and is down to make this a commitment, I received positive feedback.

[daviddias]

#225 (comment)

here:

• https://github.com/ipfs/js-ipfs#packages
• https://github.com/libp2p/js-libp2p#packages

[RichardLitt]

@diasdavid Why don't I just do all of the changes to the documentation you suggest, and then we can hash out in the PR if there are any difficulties? Will make it easier.

[daviddias]

@RichardLitt that sounds good to me :)

[daviddias]

@RichardLitt we really need some of these things urgently, starting with the shift from ^ to ~ while we are still pre-1.0.0, a lot of people have troubles with this. //cc @nicola

[RichardLitt]

@diasdavid Thank you for bringing that up. I'll highlight this on my list, and get to it in the next few days.

[RichardLitt]

List out every package in js-ipfs and js-libp2p main repo that those modules use (created by us) and add a column with their main Captain

This should be done with project-repos, I think. Or, at least, the captains should be noted there. Why did you think this would be useful?

[RichardLitt]

There should be no dependencies that rely in commits, instead there should be WIP PR and each PR that depends in other WIP PR should list what it depends too and yes, everyone will have to do the extra work of npm link everything, but that is what avoids most problems

I don't feel like this is organic or coming from the team; it looks like it is you, @diasdavid, saying this (as you can tell from your explaining how it will help and yes it is hard). I don't want to open a PR for this, because I don't think it has been discussed enough. Can you point me to the issue you make // have made on this?

[RichardLitt]

update the .*ignore examples https://github.com/ipfs/community/blob/master/js-project-guidelines.md#gitignore

@diasdavid Can you point me to a better one, or PR that?

[RichardLitt]

Have a clause that every module below 1.0.0 should use~ instead of ^. Submit PR to change all of these in all the modules

Is this for js-ipfs, all js- modules, or just all modules in general in the package.json? Can you show me an example of a working package.json file you like?

[daviddias]

@RichardLitt all of the items that I listed above were discussed during the gathering and agreed upon, nevertheless, to clarify:

re: #225 (comment)

project-repos might also be also a place for this information to live, however, it wasn't what we came out from the roundtable as an action item.

re: #225 (comment)

It is actually the other way around, organically we have been doing the WIP PR across js-ipfs and js-libp2p module ecosystem, it was a thing that me, @dignifiedquire and other contributors have adopted organically, however, since it was never claimed as being part of the process, other users of the project, i.e @haadcode with Orbit, used commits to install module dependencies and had major issues because of that (i.e September).

This was brought up several times during lab week and as far as I can tell, the people that were at the JS round table agreed that we should limit ourselves and do WIP PR, so it is explicit which WIP branches depend on which WIP branch.

re: #225 (comment)

Absolutely, every single js- repo share their .npmignore and .gitignore, the templates were never updated, see https://github.com/ipfs/js-ipfs as a good example (although all the other repos will contain the same)

re: #225 (comment)

This is just for our own module dependencies.

Hope this helps, let me know if any other questions. Thank you :)

[daviddias]

I'll take on this one: #225 (comment) as part of - ipfs/js-ipfs#756

[RichardLitt]

List all Js repos

Thee are 1871 dependencies for js-ipfs. Should I just list all ipfs/js-* and libp2p/js-* repos and leave it at that? Or ought I to be doing some more intelligent test?

Dependencies on commits

Opening a PR now.

.gitignore

looks like @diasdavid is getting it.

Tilde clause

Creating a PR now.

[daviddias]

I handled switching ^ to ~

---

Note my note above "created by us". I meant completing these tables:

• https://github.com/ipfs/js-ipfs#packages
• https://github.com/libp2p/js-libp2p#packages

And adding an extra column to identify the 'Lieutenant' for that package.

[RichardLitt]

Sorry, I was not clear enough. I am not the best person to know what extra modules are created by us which are relevant. Someone who is more familiar with the actual ecosystem should be doing this.

[daviddias]

continuation of this work is on #253