[COMPASS-7358] [Developer experience] CONTRIBUTING.md does not mention prerequisites; "Getting started" steps are incomplete and cannot be executed Created: 18/Oct/23  Updated: 01/Nov/23  Resolved: 01/Nov/23

Status: Closed
Project: Compass
Component/s: None
Affects Version/s: None
Fix Version/s: No version

Type: Bug Priority: Minor - P4
Reporter: Inga L Assignee: Unassigned
Resolution: Won't Do Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

OS: Alpine Edge (with nodejs and npm packages from v3.16) x86_64.
node.js / npm versions: v16/v8


Documentation Changes: Not Needed

 Description   

Problem Statement/Rationale

What is going wrong? What action would you like the Engineering team to take?
Cannot follow steps in "Getting started" in CONTRIBUTING.md. It would be nice if "Getting started" section listed all the prerequisites needed to get going. This can probably also affect the onboarding of the new internal contributors.

Steps to Reproduce

How could an engineer replicate the issue you’re reporting?
On fresh Alpine Edge system with v3.16 repository added (should probably also work on fresh Alpine v3.16 system; on other distributions the results will probably be slightly different): install nodejs and npm packages from v3.16 repository (since https://github.com/mongodb-js/compass/blob/main/CONTRIBUTING.md says that you'll need older node v16 and npm v8, and this is the latest Alpine version that has these); install git.
Then clone compass repository, and, as CONTRIBUTING.md instructs: navigate to the repository and run `npm run bootstrap`.

Expected Results

What do you expect to happen?
`npm run bootstrap` finishes successfully.

Actual Results

What do you observe is happening?
Some errors are produced; fixing them results in more errors; some of them require effort to figure out how to fix them. Not all errors seem to be fixable.

Additional Notes

Any additional information that may be useful to include.
It seems that at least `python3`, `gcc`, `g++`, `make` and `krb5-dev` are required for `npm install` in the root monorepo directory (first part of what `npm run bootstrap` does) to finish successfully. This list is incomplete, because I didn't even manage to get `npm install` to finish successfully.

Some specific examples:

  • While CONTRIBUTING.md says "You'll need node ^16 and npm ^8 installed on your machine to work with the repository locally", actual requirements in `package.json` are `"node": ">=16.15.1"` and `"npm": ">=8.19.4"`. So while e.g. node v18 and npm v10 satisfy these requirements, npm v8.10 (from Alpine v3.16 repository) does satisfy them. This can be solved easily enough;
  • `compass-shell` subpackage depends on `node-runtime-worker` which depends on `interruptor` (by MongoDB) which, according to its readme (https://github.com/mongodb-js/interruptor) does not provide any pre-built binaries, so one has to manually figure out what dependencies does it need to be built; there are several more examples like that, but all seem to eventually be solved by installing `python3`, `make`, `gcc` and `g++`;
  • Several subpackages including `compass` depend on `kerberos` (by MongoDB), which, according to its readme (https://www.npmjs.com/package/kerberos), requires "Distribution-specific kerberos packages". This is solved by installing `krb5-dev` package, but some effort was required to figure that out when the only thing I had was the error message saying that `gssapi/gssapi.h` is not found;
  • Several subpackages, including `compass`, depend on `mongodb-client-encryption`, which I wasn't able to get to install on my system at all (related issue: MONGOCRYPT-600);
  • There are probably more issues, but I didn't go further after getting stuck at `npm run bootstrap` (or `npm install`) failing with MONGOCRYPT-600.

None of these issues are very significant, but they block outside contributors from following CONTRIBUTING.md, and might also make developer experience worse for new internal contributors (unless this is already resolved in some internal onboarding document).

Unfortunately, because the list of issues above is non-exhaustive (because I wasn't able to get even `npm install` to finish successfully), I cannot submit any patch to CONTRIBUTING.md.



 Comments   
Comment by Inga L [ 01/Nov/23 ]

Just an update: I was able to run npm run bootstrap on Ubuntu 22.04 LTS with Node v16 and npm v8, but I still had to install g++ and make (but nothing else). I was even able to run some tests.

So updating CONTRIBUTING.md with the list of supported systems (Alpine is definitely not supported, Ubuntu 22.04 LTS seems to be supported... what else is?) and mentioning that standard node-gyp dependencies are required should be enough to resolve this ticket (and to simplify onboarding for new contributors)

Comment by Inga L [ 01/Nov/23 ]

Hi julia.oppenheim@mongodb.com, thank you for the feedback. I've just researched things a bit deeper and it seems that Alpine support is a problem in general for MongoDB, both for the server and the tools (e.g. SERVER-36790 and PHPC-1555). So you're right, and inability to follow the steps in CONTRIBUTING.md on Alpine is indeed not a huge problem at the moment, because nothing else mongo-related will work on Alpine anyway, not now at least. (It might be interesting for me to try to tackle this at some point in the future... after all, being able to run tooling on developer's OS of choice, from some point of view, can also be said to be a part of developer experience that dev tools team tries to improve, so that's not something completely unrelated 🙂)

I'll try to set up an Ubuntu container later and see if I encounter any problems with it. My guess is that I'll still have to install `make`, `gcc`, `krb5-dev` etc, so it might still be worth it to update CONTRIBUTING.md with the list of prerequisites (and mention that only some systems, such as Ubuntu, are supported for contributors).

Comment by Julia Oppenheim [ 01/Nov/23 ]

Hi inga.lovinde@outlook.com - we're closing this ticket for now, as this is a pretty specific edge case. We will revisit the priority of this in the future if it continues to come up. Thank you for your attention to this! 

Comment by Inga L [ 18/Oct/23 ]

There is a mistype in the issue description, but I don't see how to edit it:

> So while e.g. node v18 and npm v10 satisfy these requirements, npm v8.10 (from Alpine v3.16 repository) does *NOT* satisfy them.

Comment by PM Bot [ 18/Oct/23 ]

Hello inga.lovinde@outlook.com, thank you for reaching out to us! The team will review your issue and get back to you soon as soon as possible.

Please review your issue to ensure you've included your environment details and have attached relevant logs (with any sensitive data redacted), so that we're best able to provide you a timely and thorough response. Thanks again!

Generated at Wed Feb 07 22:46:17 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.