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 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 also 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. Export users can further customize the deployment (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 same 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 latest changes.

⚠️ Telepresence might occasionally get stuck when the connection with your laptop is lost and the URL lead to a 50x page. 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 Cypress 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. Here is a list of the most important tools and when they do:
  • 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) with 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.
• Try to use similar patterns: we don't have a comprehensive list, but you check the solutions used in the UI and try to re-use them. Every deployment has a Storybook section available at <base_URL>/storybook/ with a list of common patterns and examples.
• 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.
• Avoid bad practices that will be marked as linting errors: you can run npm run lint to see what's 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

🧪 Test

🚧 TODO