EGI-Federation / documentation

Sources to build EGI documentation site.
https://docs.egi.eu/
MIT License
13 stars 46 forks source link

Re-organise contributor page for development environment #637

Open brucellino opened 4 months ago

brucellino commented 4 months ago

Re-organise development environment page

In order to contribute anything, you likely need the dev env working. I hold that this should be on a single page.

In the page https://docs.egi.eu/about/contributing/git/#installing-dependencies there is mention of installing NodeJS as a dependency. I propose suggesting the use of NVM.sh for contributors to manage various Node versions:

➜ nvm use 12                        
Now using node v12.22.0 (npm v6.14.11)                    /2.5s

08:49:23 in egi-documentation on  main [!?] took 2.5s 
➜ nvm use 20
Now using node v20.11.0 (npm v10.2.4)

NVM.sh is just a shell script which can be added using the curl - | bash method, and provides functionality similar to python's virtual environments.

Further, it's stated that NodeJS 12 should be used in the environment, but this is not declared anywhere. We should add it to package.json

{
  "engines": {
    "node": "12"
  }
}

Finally, if we merge #636 we will obviate the need for many of the local tests reproducing the checks run in the actions CI checks, since they will be taken care of by the pre-commit framework. For now, I propose keeping the existing documentation, but instructing contributors to install the pre-commit hooks when contributing.

Summary of proposed changes

I propose:

  1. Create a specific page for setting up the development environment
    1. Propose use of NVM for Node
    2. Explain how to install pre-commit hooks
  2. Declare dependencies explicitly
sebastian-luna-valero commented 3 months ago

Today I just came across https://github.com/flox/flox which may also help us keep a consistent environment throughout.

brucellino commented 3 months ago

This actually looks like a really good idea. I was going to suggest using asdf instead, but I was convinced by this comment in the Elixr forum. Coming from the Nix world, and assuming the project will be stable long term, it looks like a good approach.