Add PR and release guidelines

[cgewecke]

Description

As discussed in chat with @nivida - these are ideas for a protocol around 1.x PRs and releases. A basic goal of 1.x has been to make improvements reliably without introducing new problems. This hasn't been achieved yet. Things we've tried include:

• More tests for browsers, clients and publishing. They've caught some bugs early but also let through serious errors. They aren't adequate in themselves.
• More thorough review - this is also missing avoidable problems.

In #3070, @alcuadrado suggested both formalizing the release process and using an rc release to sanity-check changes. Following this advice would have yielded better results on 1.2.3 / 1.2.4 especially.

The idea of this doc is to define a conservative approach to

• the kinds of changes we make to 1.x
• the way releases are executed.

It's a draft - likely vague, too restrictive, and/or too permissive in some places. Any constructive advice on this topic from anyone in the community is more than welcome.

Sources for the doc include

• Parity contributions docs
• Ethers contributions docs

[coveralls]

Coverage remained the same at 84.875% when pulling c1e2a16 on docs/prs-and-releases into 0f7e3dc on 1.x.

[nivida]

Do you know what kind of contributor rules Grid and EthereumJS do have?

[cgewecke]

Do you know what kind of contributor rules Grid and EthereumJS do have?

Good question. They are here...

• Grid contributions docs
• Ethereum-js contributions guidelines

[holgerd77]

Our (EthereumJS) contribution guide is rough and somewhat generic, I wrote this together some time ago to have at least something as a starting point and where we can point new contributors to.

I would agree that this also would make sense to have this in a shared documentation, see also ethereum/js-team-organization#4.

//cc @marcgarreau

[alcuadrado]

Thanks for this initial proposal, @cgewecke.

I also agree that this kind of documentation and guidelines would be most effective if shared across the entire EF JS team, but elaborating that shared guidelines, especially getting into agreement about them, can be a significant though worthy task.

In the meantime, I think almost any guideline would drastically improve web3.js' situation. The complete lack of one is holding the project back, as now discussions have to be based exclusively on mismatching personal opinions.

[wolovim]

I think this is a great draft and a good starting point for some EF JS team-wide discussion. I've added it to the agenda doc. Agree with @alcuadrado, though: don't let the team-wide discussion block you from something that immediately improves your baseline. We can fine-tune later.

[cgewecke]

Some of the things are meant to be quite specific to the demands of this branch fwiw.

A very low risk appetite / strict release protocol might be counter-productive on other projects (or even on 2.x here).

Maybe that's a nuance that could be captured in any future general documentation....that there are different criteria for high stability branches vs. things in earlier stages of development.

[nivida]

@cgewecke I was going through the issue list and found the following also CONTRIBUTIONS.md related issue: #2704. We should probably add a small guidance section for contributions that are related to type definitions.

[cgewecke]

@nivida RE: types - good point, thanks for that link. I see in that thread that what the guidelines should be is still under discussion...not sure what to add. Maybe that can be done at a later date.

[princesinha19]

@cgewecke Actually we wanted that, there should be a list of typescript guidelines which should be followed during declare of typings in case of any change. Like, during declare of typings one should not use any. Also, one should use T[ ] for transaction arrays and not Array for the sake of consistency in the module. I agree that it can be done at a later stage. Maybe @joshstevens19 and @nivida can also suggest some good points.

[princesinha19]

Also, we can add what to do before creating PR, Likto run tests and rebase the branch, etc. @nivida what is your suggestion here.

[nivida]

@princesinha19

@nivida can also suggest some good points.

Let us create those typescript related contributions rules in a separate PR later it is currently more important to have those release and PR guidelines merged.

Also, we can add what to do before creating PR, Likto run tests and rebase the branch, etc. @nivida what is your suggestion here.

I'm totally fine in the way currently PRs do get opened and I think we can add such rules if they are required later. Because as bigger the CONTRIBTUIONS.md file is as less dev do actually read it ;)

@cgewecke Thanks for writing this up! To be sure those guidelines are aligned with the EthereumJS rules do I think is one last review from @alcuadrado required and we can merge it 🎊

[alcuadrado]

This looks good. I think it should be enough for the first iteration.