Create Improvements To Contributing Page

src/SUMMARY.md

@@ -36,11 +36,16 @@
     - [Event Loop](internals/darlingserver/event-loop.md)
   - [Additional Resources](internals/additional-resources.md)
 - [Contributing](contributing/README.md)
-  - [Debugging](contributing/debugging.md)
-  - [Generating stubs](contributing/generating-stubs.md)
-  - [Generating syscalls](contributing/generating-syscalls.md)
-  - [High priority stuff](contributing/high-priority-stuff.md)
-  - [Google Summer of Code](contributing/google-summer-of-code.md)
-  - [Packaging](contributing/packaging.md)
-  - [Updating sources](contributing/updating-sources/README.md)
-
+  - [Setting Build Environment](contributing/setting_build_environment.md)
+  - [Beginner Tasks](contributing/beginner_tasks/README.md)
+    - [Generating stubs](contributing/beginner_tasks/generating-stubs.md)
+  - [Advance Tasks](contributing/advance_tasks/README.md)
+    - [Debugging](contributing/advance_tasks/debugging.md)
+    - [Updating sources](contributing/advance_tasks/updating-sources/README.md)
+      - [Generating syscalls](contributing/advance_tasks/updating-sources/generating-syscalls.md)
+  - [Submitting Your Changes](contributing/submitting_your_changes.md)
+- [Guidelines](guidelines.md)
+- [Packaging](packaging.md)
+- [Misc](misc/README.md)
+  - [High priority stuff](misc/high-priority-stuff.md)
+  - [Google Summer of Code](misc/google-summer-of-code.md)

src/contributing/README.md

@@ -1,45 +1,125 @@
 # Contributing
 
-If you are familiar with how GitHub Pull Requests work, you should feel right at home contributing to Darling. 
+## Understanding the structure of the Darling project
 
-## Fork the repository
+### Submodules
+
+The Darling project relies heavily on the usage of submodules. The best way to understand a submodule is to think of it as repo inside of another repo.
+
+The [`.gitmodules` file](https://github.com/darlinghq/darling/blob/master/.gitmodules) provides a list of submodules that the `darling` repo uses.
+
+For example, let's take a look at the `darling-xnu` repo that the `darling` repo includes.
+
+```
+[submodule "src/external/xnu"]
+path = src/external/xnu
+url = ../darling-xnu.git
+```
+
+The path indicates the location of the submodule, while the url is the link to the git repo.
+
+> [!NOTE]
+> A git submodule's URL path would usually be absolute instead of relative.
+> ```
+> [submodule "src/external/xnu"]
+> path = src/external/xnu
+> url = https://github.com/darlinghq/darling-xnu.git
+> ```
+> However, the Darling team has made the deliberate decision to use a relative path instead, mainly for the following reasons:
+> * To allow cloning/updating the project either through `https` or `ssh`
+> * To make it easier to hard fork this project.
+
+When you `cd` into the `src/external/xnu` directory, you are working off of the `darling-xnu` repo, instead of the usual `darling` repo.
+
+```bash
+cd ~/Downloads/darling
+git remote -v
+# origin  https://github.com/darlinghq/darling.git (fetch)
+# origin  https://github.com/darlinghq/darling.git (push)
+```
+```bash
+cd ~/Downloads/darling/src/external/xnu
+git remote -v
+# origin  https://github.com/darlinghq/darling-xnu.git (fetch)
+# origin  https://github.com/darlinghq/darling-xnu.git (push)
+```
+
+[For additional details on git submodules, we recommend reading the submodule section in the git-scm website](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+## Setting up your development environment
+
+If you have not already, [please see instruction page for guidance on how to set up and build Darling.](../build-instructions.md)
+
+We recommend adding the following additional flags when configuring the project with cmake:
+
+```bash
+cmake .. -DCMAKE_BUILD_TYPE=Debug -DCOMPONENTS=all
+```
+
+## Creating your fork
+
+Unless you are one of the core Darling developers who has write access to the Darling repos, you will need to create a fork to push your changes to. [If you are unsure about how to fork a repository on GitHub, please refer to the following instructions for guidance.](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository)
+
+If the changes you want to make live in a submodule (usually located in `src/external`. [See `.gitmodules` file for a list of all of the submodules Darling uses](https://github.com/darlinghq/darling/blob/master/.gitmodules)), you’ll need to `cd` into the submodule’s directory and use git remote to get the URL
 
-Locate the repository that you made changes in on GitHub. The following command can help. 
-
 ```bash
-cd darling/src/external/less
+cd src/external/xnu/
 git remote get-url origin
-https://github.com/darlinghq/darling-less.git
 ```
-If it is an `https` scheme then you can paste the URL directly into your browser. 
+```
+https://github.com/darlinghq/darling-xnu.git
+```
 
-Once at the page for the repository you made changes to, click the *Fork*
-button. GitHub will then take you to the page for your fork of that repository.
-The last step here is to copy the URL for your fork. Use the Clone or download
-button to copy it.
+Normally, you are expected to create a clone of your fork and commit your changes on that cloned fork. For Darling, we recommend working off the official repo clone you created earlier and add your fork as an additional remote.
 
-# Commit and push your changes
+# Adding your fork as an additional remote
 
-Create and check out a branch describing your changes. In this example, we will
-use `reinvent-wheel`. Next, add your fork as a remote.
+By default, a fresh clone of Darling will have the following remote:
 
 ```bash
-git remote add my-fork git@github.com:user/darling-less.git
+git remote -v
+```
+```
+origin  https://github.com/darlinghq/darling.git (fetch)
+origin  https://github.com/darlinghq/darling.git (push)
 ```
 
-After this, push your commits to your fork. 
+Use `git remote add` to add your forked repo, like so:
+
+```bash
+git remote add <YOUR GITHUB USERNAME> https://github.com/<YOUR GITHUB USERNAME>/darling.git
+```
+
+If you are working off of a submodule, make sure to `cd` into the submodule’s directory first and use the forked submodule URL:
+
+```bash
+cd src/external/xnu/
+git remote add <YOUR GITHUB USERNAME> https://github.com/<YOUR GITHUB USERNAME>/darling-xnu.git
+```
+
+If you did it correctly, you should see the following:
+
+```bash
+git remote -v
+```
+```
+<YOUR GITHUB USERNAME>    https://github.com/<YOUR GITHUB USERNAME>/darling.git (fetch)
+<YOUR GITHUB USERNAME>    https://github.com/<YOUR GITHUB USERNAME>/darling.git (push)
+origin  https://github.com/darlinghq/darling.git (fetch)
+origin  https://github.com/darlinghq/darling.git (push)
+```
+
+## Pushing your changes to your fork
+
+After you have created a branch and committed your changes, you can push your commits to your fork by using the following command.
 
 ```bash
-git push -u my-fork reinvent-wheel
+git push -u <YOUR GITHUB USERNAME> <BRANCH NAME>
 ```
 
-The `-u my-fork` part is only necessary when a branch has never been pushed to your fork before. 
+The `-u <YOUR GITHUB USERNAME>` part is only necessary when a branch has never been pushed to your fork before.
 
-# Submit a pull request
+## Submit a pull request
 
-On the GitHub page of your fork, select the branch you just pushed from the
-branch dropdown menu (you may need to reload). Click the *New pull request*
-button. Give it a useful title and descriptive comment. After this, you can
-click create.
+On the GitHub page of your fork, select the branch you just pushed from the branch dropdown menu (you may need to reload). Click the *New pull request* button. Give it a useful title and descriptive comment. After this, you can click create.
 
-After this, your changes will be reviewed by a Darling Project member.
+After this, your changes will be reviewed by a Darling project member.

src/contributing/advance_tasks/README.md

@@ -0,0 +1,3 @@
+# Advance Tasks
+
+*TODO*

src/contributing/beginner_tasks/README.md

@@ -0,0 +1,3 @@
+# Beginner Tasks
+
+*TODO*

src/contributing/setting_build_environment.md

@@ -0,0 +1,3 @@
+# Building
+
+*TODO*

src/contributing/submitting_your_changes.md

@@ -0,0 +1,3 @@
+# Submitting Your Changes
+
+*TODO*

src/guidelines.md

@@ -0,0 +1,3 @@
+# Guidelines
+
+*TODO*

src/misc/README.md

@@ -0,0 +1 @@
+# Misc