{
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "# 1.3: First steps in Trixi.jl: Changing Trixi.jl itself"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "**Note:** To improve responsiveness via caching, the notebooks are updated only once a week. They are only\n",
    "available for the latest stable release of Trixi.jl at the time of caching."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "If you plan on editing Trixi.jl itself, you can download Trixi.jl locally and run it from\n",
    "the cloned directory."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Forking Trixi.jl"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "To create your own fork of Trixi.jl, log in to your GitHub account, visit the\n",
    "[Trixi.jl GitHub repository](https://github.com/trixi-framework/Trixi.jl) and click the `Fork`\n",
    "button located in the upper-right corner of the page. Then, click on `Create fork` in the opened\n",
    "window to complete the forking process."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Cloning Trixi.jl"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Windows"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "If you are using Windows, you can clone Trixi.jl by using the GitHub Desktop tool:\n",
    "- If you do not have a GitHub account yet, create it on\n",
    "  the [GitHub website](https://github.com/join).\n",
    "- Download and install [GitHub Desktop](https://desktop.github.com/) and then log in to\n",
    "  your account.\n",
    "- Open GitHub Desktop, press `Ctrl+Shift+O`.\n",
    "- In the opened window, navigate to the `URL` tab and paste `trixi-framework/Trixi.jl` or\n",
    "  `YourGitHubUserName/Trixi.jl` to clone your own fork of Trixi.jl, and choose the\n",
    "  path to the folder where you want to save Trixi.jl. Then click `Clone` and Trixi.jl will be\n",
    "  cloned to your computer."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Now you cloned Trixi.jl and only need to tell Julia to use the local clone as the package sources:\n",
    "- Open a terminal using `Win+r` and `cmd`. Navigate to the folder with the cloned Trixi.jl using `cd`.\n",
    "- Create a new directory `run`, enter it, and start Julia with the `--project=.` flag:\n",
    "  ```shell\n",
    "  mkdir run\n",
    "  cd run\n",
    "  julia --project=.\n",
    "  ```\n",
    "- Now run the following commands to install all relevant packages:\n",
    "  ```julia\n",
    "  using Pkg; Pkg.develop(PackageSpec(path=\"..\")) # Tell Julia to use the local Trixi.jl clone\n",
    "  Pkg.add([\"OrdinaryDiffEq\", \"Plots\"])  # Install additional packages\n",
    "  ```"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Now you already installed Trixi.jl from your local clone. Note that if you installed Trixi.jl\n",
    "this way, you always have to start Julia with the `--project` flag set to your `run` directory,\n",
    "e.g.,\n",
    "```shell\n",
    "julia --project=.\n",
    "```\n",
    "if already inside the `run` directory."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Linux"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "You can clone Trixi.jl to your computer by executing the following commands:\n",
    "```shell\n",
    "git clone git@github.com:trixi-framework/Trixi.jl.git\n",
    "# If an error occurs, try the following:\n",
    "# git clone https://github.com/trixi-framework/Trixi.jl\n",
    "cd Trixi.jl\n",
    "mkdir run\n",
    "cd run\n",
    "julia --project=. -e 'using Pkg; Pkg.develop(PackageSpec(path=\"..\"))' # Tell Julia to use the local Trixi.jl clone\n",
    "julia --project=. -e 'using Pkg; Pkg.add([\"OrdinaryDiffEq\", \"Plots\"])' # Install additional packages\n",
    "```\n",
    "Alternatively, you can clone your own fork of Trixi.jl by replacing the link\n",
    "`git@github.com:trixi-framework/Trixi.jl.git` with `git@github.com:YourGitHubUserName/Trixi.jl.git`."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Note that if you installed Trixi.jl this way,\n",
    "you always have to start Julia with the `--project` flag set to your `run` directory, e.g.,\n",
    "```shell\n",
    "julia --project=.\n",
    "```\n",
    "if already inside the `run` directory."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Developing Trixi.jl"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "If you've created and cloned your own fork of Trixi.jl, you can make local changes to Trixi.jl\n",
    "and propose them as a Pull Request (PR) to be merged into `trixi-framework/Trixi.jl`."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Linux and MacOS utilize the `git` version control system to manage changes between your local and\n",
    "remote repositories. The most commonly used commands include `add`, `commit`, `push` and `pull`.\n",
    "You can find detailed information about these functions in the\n",
    "[Git documentation](https://git-scm.com/docs)."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "For Windows and GitHub Desktop users, refer to the\n",
    "[documentation of GitHub Desktop](https://docs.github.com/en/desktop/overview/getting-started-with-github-desktop#making-changes-in-a-branch)."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "After making local changes to Trixi.jl and pushing them to the remote repository, you can open a\n",
    "Pull Request (PR) from your branch to the main branch of `trixi-framework/Trixi.jl`. Then, follow\n",
    "the Review checklist provided in the Pull Request to streamline the review process."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Additional reading"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "To further delve into Trixi.jl, you may have a look at the following introductory tutorials.\n",
    "- Behind the scenes of a simulation setup will guide\n",
    "  you through a simple Trixi.jl setup (\"elixir\"), giving an overview of what happens in the\n",
    "  background during the initialization of a simulation. It clarifies some of the more\n",
    "  fundamental, technical concepts that are applicable to a variety of (also more complex)\n",
    "  configurations.\n",
    "- Introduction to DG methods will teach you how to set up a\n",
    "  simple way to approximate the solution of a hyperbolic partial differential equation. It will\n",
    "  be especially useful to learn about the\n",
    "  [Discontinuous Galerkin method](https://en.wikipedia.org/wiki/Discontinuous_Galerkin_method)\n",
    "  and the way it is implemented in Trixi.jl.\n",
    "- Adding a new scalar conservation law and\n",
    "  Adding a non-conservative equation\n",
    "  describe how to add new physics models that are not yet included in Trixi.jl.\n",
    "- Callbacks gives an overview of how to regularly execute specific actions\n",
    "  during a simulation, e.g., to store the solution or adapt the mesh."
   ],
   "metadata": {}
  }
 ],
 "nbformat_minor": 3,
 "metadata": {
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.10.3"
  },
  "kernelspec": {
   "name": "julia-1.10",
   "display_name": "Julia 1.10.3",
   "language": "julia"
  }
 },
 "nbformat": 4
}