Develop

Develop

ℹ️ This section refers to the React-based client and the Cypress tests. The Express-based server is deprecated.

Developing for Renku UI is easy! You will only need a recent version of NodeJS, NPM and Git.

💭 Should I contribute?

Everyone is welcome to contribute! You can pick any issue from the Issues section. We keep that list curated so that all entries are actionable, but feel free to ask in a comment when in doubt.

Trivial fixes, like correcting typos or adjusting classes, don't need a reference issue. New features or bigger changes that do not reference an issue should be first discussed in the Discussions section to be sure the necessary details have been taken into account (E.G: backend/networking changes required?).

🏃 Getting started

Once you clone the Renku UI repository locally, go into the client folder and install the dependencies with the npm install command. You can now start the Vite server with the command npm run start and the interface will be available at the local URL localhost:3000.

The web interface requires some backend components, and there are two ways to have them:

• Create a full Renkulab deployment for development (re-using a public instance like renkulab.io isn't currently supported out-of-the-box).
• Mock the responses from the APIs.

The first approach is recommended since all the backend resources will be available, but it requires access to the SDSC Kubernetes infrastructure. This is available to all the official Renku team members and can be extended to other SDSC employees and collaborators. Mind that deploying all the infrastructure separately is technically feasible but overkill.

The second approach relies on the existing Cypress tests in the tests folder that mock many responses from the APIs. It's much quicker and has no additional requirements, but it might be tedious if you need to mock many new responses.

Full deployment

If you have access to a full Renkulab dev deployment on the SDSC Kubernetes infrastructure, you can use Telepresence to swap the renku-ui pod with a local instance of the UI. That requires installing Docker and Kubectl to run a local instance of the UI and connect to the cluster.

The easiest way to get a deployment up and running is to use our CI automation on GitHub. Create a new PR with at least one commit and include a line with the text /deploy in the description. This will trigger the acceptance-tests workflow that deploys a dev instance of Renkulab reachable at the URL https://renku-ci-ui-<PR_number>.dev.renku.ch/. The process takes a few minutes and Renku Bot will post the exact URL. The deployment can be further customized (renku-action reference).

You can now run the run-telepresence script, provide the PR number, and access the instance from the URL you got from Renku Bot. Mind that it takes up to a minute for the new telpresence-injected pod to start serving pages; until that moment, the page you get won't come from your local code.

ℹ️ The CI workflow will update the deployment every time you commit and push to the PR. This means the deployment will be updated within a few minutes with your latest additions and, as soon as you stop telepresence, an up-to-date UI pod will pick your changes.

⚠️ Telepresence might occasionally get stuck when the connection with your laptop is suddenly lost. When that happens, the UI won't load and you'll see a 50x page instead. The quickest fix requires running telepresence uninstall --all-agents and wait until a new pod comes online. You can then re-start telepresence.

Mock responses

You can use the Cypress tests in the tests folder to mock API responses easily. There are no additional requirements.

See the Tests section for further information.

🧑‍💻 Coding guidelines

If you wish to contribute new Pull requests, your code must satisfy specific standards we have set to simplify collaboration with the broader community.

• Use the right tool for the right purpose: we stick to frameworks instead of reinventing the wheel. These includes:

  • Bootstrap: use the classes provided by Boostrap instead of creating new classes. For most components, they are sufficient. Feel free to pick the abstracted Bootstrap-specific components from Reactstrap.
  • Redux Toolkit: fetch the code from the APIs using the tools from RTK Query. Store volatile data (E.G. user inputs) using local React states. If you really need to share data with other components, creating new slices with RTK is fine, but consider encoding the information in the URL wherever it makes sense (E.G. search filters in query parameters and modals/offcanvas state in URL hashes) to guarantee smooth navigation.

  If you are in doubt, check other files in the /client/src/features folders and see how things are handled in other components.

• Try to use similar UX patterns: we try to keep the UX consistent everywhere by re-using similar components and interactions. Every deployment has a Storybook section available at <base_URL>/storybook/ with a list of common patterns and examples. When in doubt, look for similar interactions in the UI, or feel free to ask before implementing a totally new pattern that might not be ideal.

• Format your code: you can run the npm run format command to format all the files automatically. We use Prettier to keep the coding style consistent. You can easily integrate it into the most popular IDEs. We recommend using the Husky automation we have in the main folder (install with npm install) to automatically format your code when committing.

• Run the linter to point out bad coding practices: you can run npm run lint to see the status of your code. We use ESLint with a few standard plugins and some customizations. As for Prettier, you can easily integrate it into most IDEs and text editors.

• Adhere to our Coding Guidelines: we don't have any automation here, but reviews will point out inconsistencies.

If you add new features or introduce bigger changes, you might need to adjust or add new tests. See the following section.

🧪 Tests

🚧 TODO