Update the contribution page for Loopback 3

[jannyHou]

Description / Steps to reproduce / Feature proposal

This is a follow up issue of story #950. We have already updated the contribution guide for Loopback 4, and should also do the same thing for LoopBack 3 docs.

• Update page https://loopback.io/doc/en/contrib/index.html
  • Separate the LB4 contribution guide from LB3 by adding a link to https://github.com/strongloop/loopback-next/blob/master/docs/CONTRIBUTING.md
  • The functional area owners page is out-of-date, I would suggest remove it.

(Feel free to add more items...)

Reference

The original proposals are tracked in comment #950 (comment) and #950 (comment), the improvement for LB4 are already addressed.

[dhmlau]

Reviewing what we have for the "contributing" docs and CONTRIBUTING.MD files in various places, there seems to be a duplication of contents. I'd like to propose the Contributing to LoopBack page will have the following structure in the sidebar:

• Governance: will bring to the governance page (no change) but contents need to be updated, e.g. clean up the functional area owners for CODEOWNERS.
• Reporting Issues: no change in this page for the scope of this task
• Contribute to 3.x: will point to CONTRIBUTING.md in loopback repo. And that CONTRIBUTING.MD needs to be updated.
• Contribute to 4.x: will point to CONTRIBUTING.md in loopback-next repo.

[bajtos]

Thank you @dhmlau for picking up this task!

Besides the comments below, I think we should also decide what to do about https://loopback.io/doc/en/contrib/triaging-pull-requests.html. I think most of the content applies to both 2.x/3.x and 4.x, but some parts need to differentiate (e.g. commit message style).

Reporting Issues: no change in this page for the scope of this task

Can we split this into v2/v3 and v4+ while we are reorganizing docs please? It will make it easier for us to write bug reporting instructions for LB4 when the doc structure is already prepared.

Contribute to 3.x

What about 2.x? Most of the 3.x documentation applies to 2.x too, the biggest difference is in the coding style.

Style guides:

• v4, out of date: https://loopback.io/doc/en/contrib/style-guide.html - we should move this to loopback-next monorepo and clean it up (eventually)
• v3: https://loopback.io/doc/en/contrib/style-guide-es6.html
• v2: https://loopback.io/doc/en/contrib/style-guide-es5.html

Contribute to 3.x: will point to CONTRIBUTING.md in loopback repo. And that CONTRIBUTING.MD needs to be updated.

To make this work, we would have to update CONTRIBUTING.md in most if not all LoopBack 3.x repositories. Keeping so many copies up to date would be super tedious and painful. Let's keep 3.x contribution docs inside loopback.io as they are now.

Contribute to 4.x: will point to CONTRIBUTING.md in loopback-next repo.

Please note that CONTRIBUTING.md is sort of a sign-post pointing to content in other documentation files. These other files are already available at loopback.io, no need to redirect people between GitHub.com and LoopBack.io. If we want to reuse the sign-post structure offered in CONTRIBUTING.md, then we should look into ways how to leverage CONTRIBUTING.md file inside loopback.io too. Note that we cannot move this file in loopback-next GitHub repository, because we need GitHub to recognize it as Contributing guide that's show in special way to people visiting GitHub (filling issues, opening pull requests).

[dhmlau]

@bajtos , thanks for your feedback. A few questions:

1. Reporting Issues
   What do you think the differences in reporting issues for v2/v3 and v4? I think the flow is generally the same and only the repos are different?

2. CONTRIBUTING.md in 4.x

Please note that CONTRIBUTING.md is sort of a sign-post pointing to content in other documentation files. These other files are already available at loopback.io, no need to redirect people between GitHub.com and LoopBack.io.

Are you thinking to put all the required information in loopback.io, and have the CONTRIBUTING.md page to point there? I'd like to avoid duplication of information if possible, because it's harder to maintain.

3. Contribute to 3.x

To make this work, we would have to update CONTRIBUTING.md in most if not all LoopBack 3.x repositories.

I was originally thinking to have the real content in the CONTRIBUTING.md in loopback repo and have other 3.x repo pointing to that md file. But I guess it's better to put it in loopback.io.

[bajtos]

Reporting Issues
What do you think the differences in reporting issues for v2/v3 and v4? I think the flow is generally the same and only the repos are different?

You are right. Most of the content is same for both pre-v4 and v4+. The biggest difference I see in "Bug report" instructions, but I guess that's something we can leave out of scope of this issue.

Please note that CONTRIBUTING.md is sort of a sign-post pointing to content in other documentation files. These other files are already available at loopback.io, no need to redirect people between GitHub.com and LoopBack.io.

Are you thinking to put all the required information in loopback.io, and have the CONTRIBUTING.md page to point there? I'd like to avoid duplication of information if possible, because it's harder to maintain.

We need to preserve CONTRIBUTING.md in loopback-next's repository, because GitHub is picking up that file to display hints and warnings in the web UI.

I agree duplicating the same information in multiple places is suboptimal as it makes the docs difficult to maintain.

On the other hand, CONTRIBUTING.md together with site/DEVELOPING.md allow people to consume our dev-related docs in offline mode, so I see value in having sign-post links in CONTRIBUTING pointing to local DEVELOPING guide instead of loopback.io.

This sounds like conflicting requirements to me :(

How about the following:

1. Keep CONTRIBUTING.md mostly as is, with the list of useful links pointing to other places in our monorepo. This file is targeting people who arrive to our contrib docs via GitHub.

2. For our docs on loopback.io, we can simplify the "sign post" section to ~2-3 of top-level links only. Our doc pages have a table-of-content generated out of the box, thus people can use that TOC for further navigation. Essentially, I think we need the following links on loopback.io, replacing the content of CONTRIBUTING.md used on GitHub:

   • general guidelines/working with GitHub: a link to a page describing the general aspects of contributing to LB: changes should be discussed in issues before opening PR, instructions for GitHub pull request workflow. I think this mostly covered by the existing content in https://loopback.io/doc/en/contrib/code-contrib.html, we just need to reorder that content.

   • contribute code: a link to site/DEVELOPING.md (e.g. /doc/lb4/DEVELOPING.md or /doc/contrib/DEVELOPING.md), that file document pretty much explains everything needed to contribute code.

   • contribute documentation: a link to the LB4 version of "contribute documentation".

Contribute to 3.x

To make this work, we would have to update CONTRIBUTING.md in most if not all LoopBack 3.x repositories.
I was originally thinking to have the real content in the CONTRIBUTING.md in loopback repo and have other 3.x repo pointing to that md file. But I guess it's better to put it in loopback.io.

I don't really mind either way, it's just that modifying CONTRIBUTING.md in all LB repositories seems to me like a waste of time to me - it means about 90 pull requests to open (if I remember the number of our repositories correctly).

[dhmlau]

Closing as resolved.
https://loopback.io/doc/en/contrib/code-contrib.html