More contributing docs

docs/contributing/documentation.md

@@ -4,12 +4,33 @@ We use [Markdown](https://www.markdownguide.org/basic-syntax/) files to generate
 The Markdown files can be found in our [public repository](https://github.com/OpenModelDB/open-model-database).
 Anyone with a GitHub account can improve the documentation of this site.
 
-This page will explain how to make changes to documentation pages.
-We assume that you have already cloned our repository onto your local machine.
-If you haven't or are new to GitHub, checkout [our guide about GitHub](github.md).
+## Changing existing pages online
+
+> _This section assumes that you already have a GitHub account and that you are logged in._
+
+Changing existing pages online is the easiest way to contribute to the documentation.
+
+1. Go to the page you want to change (e.g. [the FAQ](https://openmodeldb.info/docs/faq)).
+2. Scroll to the bottom and click on the "Edit this page on GitHub" button. This will open GitHub, where you can edit the page.
+    - If you are not logged in, you will be asked to log in first.
+    - GitHub might ask you to fork the project first. This is necessary, so click the "Fork this repository" button.
+3. Make your changes.
+    - GitHub's online Markdown editor has a preview feature, so you can see how your changes will look like.
+    - You can also use the "Show Diff" option to make GitHub highlight the changes you made.
+4. Once you are done, click the "Commit changes..." button.
+5. GitHub will now ask for a commit message and an extended description.
+    - The commit message is a very short description of what you did (e.g. "Fix typo", "Expand on section XYZ", "Add more examples to XYZ"). This is required.
+    - The extended description is where you explain your changes in more detail. Explain what you did and why you did it. This is optional but highly recommended, especially if you did more than just fix a typo.
+6. Click the "Propose changes" button.
+7. Click on the "Create pull request" button.
+8. Click on the "Create pull request" button again.
+
+Done! Your changes will be reviewed by the moderators/maintainers of the project shortly. After they have looked over your changes and made sure that everything is in order, they will either approve your changes or request further changes (e.g. we might ask you to fix a typo you made).
 
 ## Changing existing pages
 
+> _This section assumes that you have [checked out the project locally](index.md#checking-out-the-project-locally) and know [how to make a pull request](index.md#how-to-make-a-pull-request)._
+
 Editing the contents of existing pages is simple.
 Just open the Markdown file of the page you want to change.
 
@@ -19,16 +40,19 @@ The only exception to this rule are index files.
 E.g. `/docs/interesting/index.md` will have the URL `https://openmodeldb.info/docs/interesting`.
 
 While most editors allow you to preview Markdown files (e.g. [VSCode](https://code.visualstudio.com/docs/languages/markdown#_markdown-preview)), you can also see your changes directly on the website.
-Just start a local dev server and navigate to the page you changed.
-Note that documentation pages will *not* update automatically when you make changes to the underlying Markdown file, you have to manually reload the page.
+Just start a [local dev server](index.md#local-dev-server) and navigate to the page you changed.
+Note that documentation pages will _not_ update automatically when you make changes to the underlying Markdown file, you have to manually reload the page.
 
 ## Adding new pages
 
+> _This section assumes that you have [checked out the project locally](index.md#checking-out-the-project-locally) and know [how to make a pull request](index.md#how-to-make-a-pull-request)._
+
 To add a new page, we must (1) add a new Markdown file and (2) add the page to the sidebar.
 
 ### New Markdown file
 
 For step one, create a new Markdown file in the `/docs` directory. E.g. a new file called `/docs/path/to/page.md` could look like this:
+
 ```md
 # Title
 

docs/contributing/index.md

@@ -0,0 +1,114 @@
+# Contributing
+
+There are many ways to contribute to the project, and we appreciate all of them.
+This page will help you get started.
+
+Before we begin: you need a [GitHub account](https://github.com) to contribute ([why?](#why-github)). If you don't have one already, create a new free account. Don't worry, you do **not** need to know git or how to code to contribute.
+
+Here are some common ways in which you can contribute to the project:
+
+-   [**Reporting bugs and suggesting features**](https://github.com/OpenModelDB/open-model-database/issues)
+
+    Help us improve the project by reporting issues you found and suggesting new features. You have an idea what will make the project better? Tell us about it!
+
+-   [**Adding models**](./models.md)
+
+    Add your latest models to the database, or help us add models from others (assuming that their license allows it).
+
+-   [**Documentation**](./documentation.md)
+
+    Help writing and improving the documentation of the project. This mostly includes writing Markdown files.
+
+## Why GitHub?
+
+GitHub is a code-sharing platform, but it also offers many other features that make it a great place to collaborate on projects. We use it to:
+
+-   Host the project's code.
+-   Host the project's website.
+-   Manage issues and have discussions.
+-   Take and review pull requests (contributions).
+
+GitHub's services are what makes this project (as it is now) possible, and the platform does all of it for free.
+
+We do everything on GitHub, so you need an account to contribute.
+
+## Checking out the project locally
+
+> This section assumes that you are at least somewhat familiar with git and GitHub. If you are not, please read [this guide](https://guides.github.com/activities/hello-world/) first.
+
+Having the project setup locally is required for many ways of contributing. E.g. code contributions absolutely require it, but some other contribution methods also need it.
+
+To check out the project, you need to have an internet connection and the following tools installed:
+
+-   git ([Download](https://git-scm.com/downloads))
+-   Node.js >=v16 ([Download](https://nodejs.org/en/download/))
+
+Once you have these tools installed, follow these steps:
+
+1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository) the [OpenModelDB repository](https://github.com/OpenModelDB/open-model-database). This will create your very own copy of the project under your account. You can then make changes to your copy.
+2. [Clone](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository) your forked repository onto your computer. This will download the project to your computer.
+3. Open a terminal and navigate to the project folder.
+4. Run `npm ci` to install the project dependencies.
+5. Run `npm run build` to build the project. If this succeeds, everything installed correctly.
+
+You now have the project installed and are ready to contribute. Open the project in your favorite editor and start making changes. We recommend using [Visual Studio Code](https://code.visualstudio.com/).
+
+## Project setup
+
+The website is a pretty standard [React](https://react.dev/) + [Next.js](https://nextjs.org/) project. We use Next.js to generate a static website that we then host on GitHub Pages.
+
+Let's take a look at the project structure. This will help you find your way around the project.
+
+-   `/data` - Contains the database. You rarely need to edit anything in this folder directly. It's easier to use the [local dev server](#local-dev-server) to make changes to the database.
+-   `/docs` - Contains the documentation of the project. This is the folder you want to edit when you want to change the documentation.
+-   `/src` - Contains the source code of the project. This includes the website, the "backend" server, and everything else needed to run the project.
+    -   `/src/elements` - Contains the UI elements of the website.
+    -   `/src/lib` - Contains most of the logic that drives everything.
+    -   `/src/pages` - Contains the individual pages of the website.
+    -   `/src/styles` - Contains some global styles.
+-   `/tests` - Contains the tests of the project.
+-   `/scripts` - Contains various scripts we use during CI.
+
+### Useful commands
+
+-   `npm run dev` - Starts the [local dev server](#local-dev-server).
+-   `npm run build` - Builds the project.
+-   `npm run lint` - Runs the linter.
+-   `npm run lint:fix` - Runs the linter and fixes any fixable errors.
+-   `npm run test` - Runs the tests.
+-   `npm run validate-db` - Runs checks on the database to ensure everything is valid.
+
+## How to make a Pull Request
+
+> _This section assumes that you have [checked out the project locally](#checking-out-the-project-locally)._
+
+GitHub has great [documentation](https://docs.github.com/en/get-started/quickstart/contributing-to-projectss) on making pull requests. We will not repeat that here. Instead, we will focus on the specifics of this project.
+
+A few things you should know about making pull requests to this project:
+
+-   Make sure that your changes are in a separate branch. Do not commit into your `main` branch. If you have conflicts, they will be harder to resolve if you commit into your `main` branch.
+-   We make use of GitHub actions to run tests and checks on your pull request. We **won't merge** your pull request until all checks pass. But don't worry. If checks fail, and you can't figure out why, feel free to ask for help in the pull request or just wait, a maintainer will help you.
+
+    Checks include tests, linting and validating the DB. You can run these checks locally using the following commands:
+
+    -   `npm run lint`
+    -   `npm run test`
+    -   `npm run validate-db`
+
+-   We **squash** all commits into a single commit when merging pull requests. This means that you don't need to force push to create a clean commit history. In fact, we recommend that you don't force push, as it makes it harder to review your changes.
+
+## Local dev server
+
+> _This section assumes that you have [checked out the project locally](#checking-out-the-project-locally)._
+
+The local dev server is a useful tool when changing the website and the database. It allows you to see your changes on a local version of the website without having to deploy to https://openmodeldb.info.
+
+To start the local dev server, run the following command:
+
+```bash
+npm run dev
+```
+
+This will start the local dev server on port 3010. You can then access the website at http://localhost:3010.
+
+The dev server will automatically reload in most cases when you make changes to the website or the database. The only real exception to this are documentation pages. When you change a documentation page, you need to reload the page to see your new changes.

docs/contributing/models.md

@@ -0,0 +1,61 @@
+# Models
+
+## Adding models online
+
+> _This section assumes that you already have a GitHub account and that you are logged in._
+
+*Work in progress*
+
+We will add a bot in the future that will allow you to add models by commenting on an issue. This means that you won't have to check out the project locally and can just do it all online. Progress on this is [tracked here](https://github.com/OpenModelDB/open-model-database/issues/255).
+
+## Adding models
+
+> _This section assumes that you have [checked out the project locally](index.md#checking-out-the-project-locally) and know [how to make a pull request](index.md#how-to-make-a-pull-request)._
+
+Start the [local dev server](index.md#local-dev-server) and open any page. There should be an "Add model" button in the header list. If not, make sure that edit mode is on. Click the "Add model" button and a new page will open.
+
+Fill in the requested information:
+
+-   If a pretrained model was used to train the model, select it from the dropdown. The page will use the pretrained model to fill in some information automatically. Otherwise, leave it as "None".
+-   Now, we need to choose an ID for the model. This ID will be used in the URL of the model page and for the model's file name (only relevant for self-hosted models). It must be unique and can only contain letters, numbers, and hyphens. It is recommended to use the name of the model as the ID.
+    -   The ID should not contain the model's scale. The scale will automatically be added to the ID when the model is added to the database.
+    -   The ID should not contain any information that can be found on the model's page (e.g. number of training iterations, number of parameters, etc.). \
+        The only exception to this is when this information is necessary to distinguish between two models with the same name. E.g. some models have multiple variants with different training iterations.
+    -   The ID is **not** the model's name. You can enter the model's name later.
+-   Enter the model's scale. This is only necessary when no pretrained model is selected.
+
+Once that is all filled in, click the "Add model" button. After a few seconds, the page of the newly added model will open. You can now edit the model's information.
+
+Just like any other model page, everything is editable. You don't have to fill in everything, but there are a few things that are required:
+
+-   The model's name.
+-   The author(s). (You might have to add the author to the user database first.)
+-   The release date. Just leave it as today's date if you are releasing the model by adding it to the database.
+-   The description. Describe what the model is intended to do. The description uses [Markdown](https://www.markdownguide.org/basic-syntax/).
+-   The model's license. If the model is yours, consider using a permissive license.
+-   Tags. These are used to categorize the model.
+-   The model architecture.
+-   The color mode.
+
+### Adding resources
+
+After you filled in this information and maybe more, it's time to add the model's files. Since a single model might consist of multiple files, we don't call them files, but "resources". A resource represents a single model.
+
+Click the "Add resource" button and fill in the requested information:
+
+-   The URL of the model's file. This can be a URL to a file on GitHub or some file hoster. Prefer using trusted file hosters like GitHub, Google Drive, Dropbox, Mega, etc. over random file hosters.
+-   The file size, checksum (SHA256), and platform. If you have the model file on your computer, you can use the "Get info from file..." button to fill in this information automatically. Just select the file and the information will be filled in.
+
+Click "Save" and the resource will be added.
+
+Note that a single resource can have multiple URLs. This is useful when the model is hosted on multiple platforms and for mirrors.
+
+### Adding images
+
+To give people an idea of what the model can do, it's a good idea to add example images.
+
+Click the `+` button below the empty image view to add either an image pair for a comparison or a single image. You can add as many images as you want. Images can also be given caption.
+
+Note: We do not host images. Using services like [imgsli](https://imgsli.com/) to host image comparisons.
+
+Since we need image URLs, and not just links to the pages of third-party image hosting services, the URL fields will try to automatically extract the image URL from the link. E.g. when you enter an imgsli link into the LR field, the LR and SR fields will automatically be filled in with the URLs of the images. We support multiple popular image hosters for this, so just paste URLs and it should work.

docs/manifest.json

@@ -13,13 +13,12 @@
 		},
 		{
 			"directory": "contributing/",
-			"title": "Contributing",
 			"routes": [
 				{
-					"file": "documentation.md"
+					"file": "models.md"
 				},
 				{
-					"file": "github.md"
+					"file": "documentation.md"
 				}
 			]
 		}