Documentation for contributing to KomaMRI using VSCode

[beorostica]

https://juliahealth.org/KomaMRI.jl/previews/PR382/

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.47%. Comparing base (647ebdf) to head (6606041).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #382   +/-   ##
=======================================
  Coverage   89.47%   89.47%           
=======================================
  Files          43       43           
  Lines        2728     2728           
=======================================
  Hits         2441     2441           
  Misses        287      287           

Flag	Coverage Δ
base	86.42% <ø> (ø)
core	86.93% <ø> (ø)
files	93.70% <ø> (ø)
komamri	93.96% <ø> (ø)
plots	89.64% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

[cncastillo]

The text is overly complicated, and the images give little information. The section's name should make sense, "How to ... Advanced Users" ? Please modify as suggested.

[cncastillo]

Installing KomaMRI as a developer

Install dev version of Koma:
Now we will use the REPL to install Koma as a developer:

pkg> dev KomaMRI

This command will clone KomaMRI.jl's repository (dev version) to ~/.julia/dev/KomaMRI.jl/.

Open Koma dev in VSCode:
Now, open this folder in VScode using File/Open Folder... in the menu bar. The Julia extension should automatically detect the KomaMRI environment. To check this, look at the status bar (bottom) and you should see Julia env: KomaMRI.jl. If this is not the case, click the option in the menu bar and select KomaMRI.jl.

KomaMRI monorepo setup:
As KomaMRI.jl contains multiple packages in one GitHub repository, you need to specify that you want to use your local copies (instead of the ones available on the Julia registries) with:

(KomaMRI) pkg> dev ./KomaMRIBase ./KomaMRICore ./KomaMRIFiles ./KomaMRIPlots

Finally, use the instantiate command to install all the required packages (specified in the Project.toml):

(KomaMRI) pkg> instantiate

This will also include all the specific package versions into the Manifest.toml. The Manifest.toml should not be uploaded to the repo when making a commit or pull request. Thus, it is present in the .gitignore.

[cncastillo]

Forking Koma

If you try to commit or generate a pull request at this point, you will get an Access denied error. This is because you need to create a fork before you can contribute to this repository directly (unless you are included as a collaborator!). To create a fork of KomaMRI.jl, go to KomaMRI.jl's GitHub and click the "Fork" button and follow the instructions:

To use you fork in VSCode click "master" in the status bar:

and select your remote branch username/KomaMRI.jl.

[cncastillo]

Suggested change

	## Setup your Fork of KomaMRI
	Once everything is installed, you need to create a fork of the KomaMRI repo in your Github account. Go to the official KomaMRI repo https://github.com/JuliaHealth/KomaMRI.jl and follow the bellow steps:
	
	
	Now, your fork of KomaMRI should look like this:
	
	Now you need to clone your fork of the KomaMRI repo. In julia you can do this by opening a terminal and typing (make sure you change the `<github-username>`):
	```julia-repl
	(@v1.10) pkg> dev https://github.com/<github-username>/KomaMRI.jl
	```
	This saves the local git project at the `~/.julia/dev/KomaMRI/` directory. You can open VScode and open this folder, it should look like this:
	
	Everything looks good. Let's run KomaMRI, but before you can do so, you need to setup the Julia environment. The information of the environment is ultimately defined by the file `Manifest.toml`, however you don't have that file yet. So you need to create it from the information of the `Project.toml`.
	Let's select the environment of our KomaMRI project:
	
	Now, open a Julia REPL:
	
	In the Julia REPL you have to create the `Manifest.toml` file with the `develop` command considering de local folders `KomaMRIBase`, `KomaMRICore`, `KomaMRIFiles` and `KomaMRIPlots`. Additionally you can install all the dependencies listed in the `Manifest.toml` with the `instantiate` command:
	```julia-repl
	(KomaMRI) pkg> dev ./KomaMRIBase ./KomaMRICore ./KomaMRIFiles ./KomaMRIPlots
	(KomaMRI) pkg> instantiate
	```
	With these steps your environment is setup. You can now run the KomaMRI user interface:
	```julia-repl
	julia> using KomaMRI
	julia> KomaUI()
	```
	
	Let's see what is the default phantom in the user interface by clicking in the `Phantom dropdown` and then press the `View Phantom` button:
	
	You can close the KomaMRI user interface.
	## Make changes to remote repos
	So far so good. However you want to make some changes to your Github Fork and even you want to contribute to the KomaMRI project. But first, let's make some local changes in the local git repo. In the following example we will change the default phantom displayed in the user interface.
	First create a branch with a descriptive name, in this case `patch-ui-default-phantom`:
	
	
	In this new branch, we are going to edit the `setup_phantom` function located in the file `src/ui/ExportUIFunctions.jl`. We simply replace the line where a brain phantom is defined by the function `pelvis_brain2D`:
	
	Then, you need to compile the function `setup_phantom`, simply put the cursor in a place inside the function `setup_phantom` and then press `Alt + Enter`:
	
	Now, let's see what is the new default phantom in the user interface by clicking in the `Phantom dropdown` and then press the `View Phantom` button:
	```julia-repl
	julia> KomaUI()
	```
	
	Everything looks good, let's stage the changes:
	
	And commit the changes:
	
	Let's upload these changes in your github fork or to the official KomaMRI repo by selecting the `origin` or the `upstream` option:
	
	
	

[cncastillo]

Commiting your first pull request

So far, so good. Let's make some changes.

Create a branch:
First, create a branch with a descriptive name, in this case my-new-cool-feature:

Make some changes to the code:
CHANGE TO SIMPLER EXAMPLE. Modify README, or something.

Commit changes:
TODO. We encourage to

Publish a pull request:
TODO

Review process:
In Koma we require all pull requests to pass our automated tests ... TODO ... do not be afraid if you get an X in nightly because ...

[curtcorum]

So far, the KomaMRI package has 4 subdirectories: KomaMRIBase, KomaMRICore, KomaMRIPlots and KomaMRIFiles. These subdirectories are julia packages by themselves, so they have their own Project.toml which is needed to resolve the environment ultimately defined by Manifest.toml. The directories are not separate git submodules.