1. SolidOS know how

The basic instructions for running setting up SolidOS and much more can be found on the SolidOS readme.

Note: We are trying our best to keep this documentation up to date. If you see something outdated we invite you to make a ticket over at SolidOS GitHub issues.

How to make code changes

As a newcomer, you do not have direct access to the repos. In this case, you can still contribute through Pull Requests (PRs). First, navigate to the repo you want to work on and create a fork. Make your changes on your form and then create a PR. We will be notified and you will receive feedback on your changes. For more details on how to do this, visit the GitHub documentation which explains it much better than we ever could.

If you do have direct access to the repos, it is usual to create a branch for your changes and then a PR. A PR helps you receive feedback and lets us know easily about any changes to the code. Read more about Pull Requests over at the GitHub documentation.

Dealing with GitHub branches

Steps to setup/run SolidOS using repos with different branches

If you only have to change in one or a few repositories

The first few steps (1-4) are also included in the main documentation mentioned above.

1. Clone the SolidOS repo.
2. Run the setup in the solidos project folder.
   npm run setup
3. Double-check the setup completed correctly by running the watch.
   npm run watch
4. Add any other pane or repo that will be modified. See the example below that pulls in the solid-logic repo.
   npm run add solid-logic or npm run add <git repo URL>
5. Within the repo that should use a different branch, pull the desired branch. See the example below.
   cd workspaces/solid-ui && git checkout <branch-name>
6. Once that has been successfully run the following command from the main SolidOS directory.
   npx lerna bootstrap --force-local
7. Lastly, the watch from Step 3 can be run again and SolidOS should be up and running.

Note: In case the change does not work, maybe a node cache clear will help with npm cache clean --force or/and npm start -- --reset-cache.

Note: Once these steps have been followed changes can be made inside any workspaces/repo-name library or pane and the change should be immediately shown in SolidOS. Changes to node-solid-server are the only exception. In this case, SolidOS may need to be restarted.

If you need to change branch for more repositories at the same time

Follow the steps from (1-4) mentioned above. Inside SolidOS there is a script that switches branches: https://github.com/solid/solidos/blob/main/scripts/switch-branch. inside the script, you can see that it ONLY switches branches of the main repos "rdflib", "solid-ui", "solid-panes", "mashlib", "node-solid-server". If you need any other repo to be switched you can simply add it to the script and then run the script with npm switchBranch <branch-name>. Please note, if a repo does not have such a that repo will stay on the branch it currently is on. Make sure to read the output messages to check if it was successful or not.

The data browser hack: upgrading your browser

This refers to a specific way in which the SolidOS is deployed for users who at first only have a conventional web browser - a hypertext browser not a data browser. It is a hack -- in the original computing sense of a crafty, though not beautiful, little thing which gets the job done.

How does the data browser work?

1. The user goes with a normal web browser to access some data object (like a to-do list).
2. The server sees the browser doesn't understand the data natively.
3. The server sends back a little placeholder HTML file, databrowser.html, instead of the data.
4. The databrowser.html file loads the mashlib.js Javascript library, which can now understand the data.
5. The mashlib.js then re-requests the original data, but accepts data formats.
6. The server supplies the actual data of the to-do list or whatever it was.
7. The mashlib.js code provides an editable visualization of the data.

The mashlib human interface is read-write: where the user is allowed to edit: it lets them edit the data and create new things. It is live, in that often the data browser signed up (using a WebSocket) for any changes which other users make, so users' screens are synchronized.

A major limitation of the data browser hack is that current web browsers are made to distrust any code loaded from one domain that uses data from another domain. This makes it hard, strangely complicated, and sometimes impossible to do some things.