-
Notifications
You must be signed in to change notification settings - Fork 21
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation for contributing to KomaMRI using VSCode #382
base: master
Are you sure you want to change the base?
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
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
Flags with carried forward coverage won't be shown. Click here to find out more. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
docs/src/how-to/4-develop.md
Outdated
## 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: | ||
|
||
![](../assets/dev-fork.png) | ||
![](../assets/dev-fork-create.png) | ||
|
||
Now, your fork of KomaMRI should look like this: | ||
|
||
![](../assets/dev-fork-github.png) | ||
|
||
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: | ||
|
||
![](../assets/dev-vscode-git-project.png) | ||
|
||
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: | ||
|
||
![](../assets/dev-vscode-select-komamri-environment.png) | ||
|
||
Now, open a Julia REPL: | ||
|
||
![](../assets/dev-open-julia-repl.png) | ||
|
||
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() | ||
``` | ||
![](../assets/dev-launch-ui.png) | ||
|
||
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: | ||
|
||
![](../assets/dev-default-phantom-brain.png) | ||
|
||
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`: | ||
|
||
![](../assets/dev-branch.png) | ||
![](../assets/dev-branch-name.png) | ||
|
||
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`: | ||
|
||
![](../assets/dev-branch-edit.png) | ||
|
||
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`: | ||
|
||
![](../assets/dev-branch-compile.png) | ||
|
||
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() | ||
``` | ||
|
||
![](../assets/dev-default-phantom-pelvis.png) | ||
|
||
Everything looks good, let's stage the changes: | ||
|
||
![](../assets/dev-stage-changes.png) | ||
|
||
And commit the changes: | ||
|
||
![](../assets/dev-commit-changes.png) | ||
|
||
Let's upload these changes in your github fork or to the official KomaMRI repo by selecting the `origin` or the `upstream` option: | ||
|
||
![](../assets/dev-publish.png) | ||
|
||
![](../assets/dev-pullreq.png) | ||
|
||
![](../assets/dev-pullreq-name.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
.
docs/src/how-to/4-develop.md
Outdated
|
||
## 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: | ||
|
||
![](../assets/dev-fork.png) | ||
![](../assets/dev-fork-create.png) | ||
|
||
Now, your fork of KomaMRI should look like this: | ||
|
||
![](../assets/dev-fork-github.png) | ||
|
||
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: | ||
|
||
![](../assets/dev-vscode-git-project.png) | ||
|
||
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: | ||
|
||
![](../assets/dev-vscode-select-komamri-environment.png) | ||
|
||
Now, open a Julia REPL: | ||
|
||
![](../assets/dev-open-julia-repl.png) | ||
|
||
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() | ||
``` | ||
![](../assets/dev-launch-ui.png) | ||
|
||
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: | ||
|
||
![](../assets/dev-default-phantom-brain.png) | ||
|
||
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`: | ||
|
||
![](../assets/dev-branch.png) | ||
![](../assets/dev-branch-name.png) | ||
|
||
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`: | ||
|
||
![](../assets/dev-branch-edit.png) | ||
|
||
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`: | ||
|
||
![](../assets/dev-branch-compile.png) | ||
|
||
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() | ||
``` | ||
|
||
![](../assets/dev-default-phantom-pelvis.png) | ||
|
||
Everything looks good, let's stage the changes: | ||
|
||
![](../assets/dev-stage-changes.png) | ||
|
||
And commit the changes: | ||
|
||
![](../assets/dev-commit-changes.png) | ||
|
||
Let's upload these changes in your github fork or to the official KomaMRI repo by selecting the `origin` or the `upstream` option: | ||
|
||
![](../assets/dev-publish.png) | ||
|
||
![](../assets/dev-pullreq.png) | ||
|
||
![](../assets/dev-pullreq-name.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
## 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: | |
![](../assets/dev-fork.png) | |
![](../assets/dev-fork-create.png) | |
Now, your fork of KomaMRI should look like this: | |
![](../assets/dev-fork-github.png) | |
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: | |
![](../assets/dev-vscode-git-project.png) | |
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: | |
![](../assets/dev-vscode-select-komamri-environment.png) | |
Now, open a Julia REPL: | |
![](../assets/dev-open-julia-repl.png) | |
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() | |
``` | |
![](../assets/dev-launch-ui.png) | |
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: | |
![](../assets/dev-default-phantom-brain.png) | |
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`: | |
![](../assets/dev-branch.png) | |
![](../assets/dev-branch-name.png) | |
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`: | |
![](../assets/dev-branch-edit.png) | |
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`: | |
![](../assets/dev-branch-compile.png) | |
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() | |
``` | |
![](../assets/dev-default-phantom-pelvis.png) | |
Everything looks good, let's stage the changes: | |
![](../assets/dev-stage-changes.png) | |
And commit the changes: | |
![](../assets/dev-commit-changes.png) | |
Let's upload these changes in your github fork or to the official KomaMRI repo by selecting the `origin` or the `upstream` option: | |
![](../assets/dev-publish.png) | |
![](../assets/dev-pullreq.png) | |
![](../assets/dev-pullreq-name.png) |
docs/src/how-to/4-develop.md
Outdated
## About Julia Environments and Subdirectories | ||
|
||
So far, the `KomaMRI` package have 4 subdirectories `KomaMRIBase`, `KomaMRICore`, `KomaMRIPlots` and `KomaMRIFiles`. These subdirectories are proper julia packages by themselves, so they have their own `Project.toml` which need to resolve an environment defined ultimately by a `Manifest.toml`. | ||
|
||
This is how these packages are related: | ||
* `KomaMRIBase` doesn't depend on any of these other subdirectories. | ||
* `KomaMRICore` depends directly on `KomaMRIBase` | ||
* `KomaMRIPlots` depends directly on `KomaMRIBase` | ||
* `KomaMRIFiles` depends directly on `KomaMRIBase` | ||
* `KomaMRI` depends directly on `KomaMRICore`, `KomaMRIPlots` and `KomaMRIFiles` | ||
|
||
If you want to edit only the direct contents of one of these packages, you simply need to activate the julia package and then instantiate to generate the `Manifest.toml` and install dependencies. However, if you want to make changes that involve the packages and it's direct dependencies you need to create an environment that indicates so. | ||
|
||
For instance, to edit `KomaMRICore` and its direct dependency `KomaMRIBase` you need to create the `Manifest.toml` like so: | ||
```julia-repl | ||
user@machine ~/.julia/dev/KomaMRI | ||
$ julia | ||
|
||
(@v1.10) pkg> activate KomaMRICore | ||
|
||
(KomaMRICore) pkg> dev ./KomaMRIBase | ||
``` | ||
|
||
And for creating the `Manifest.toml` file of `KomaMRI`which considers all the subdirectories you have to do: | ||
```julia-repl | ||
user@machine ~/.julia/dev/KomaMRI | ||
$ julia | ||
|
||
(@v1.10) pkg> activate . | ||
|
||
(KomaMRI) pkg> dev ./KomaMRIBase ./KomaMRICore ./KomaMRIFiles ./KomaMRIPlots | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 ...
docs/src/how-to/4-develop.md
Outdated
|
||
## About Julia Environments and Subdirectories | ||
|
||
So far, the `KomaMRI` package have 4 subdirectories `KomaMRIBase`, `KomaMRICore`, `KomaMRIPlots` and `KomaMRIFiles`. These subdirectories are proper julia packages by themselves, so they have their own `Project.toml` which need to resolve an environment defined ultimately by a `Manifest.toml`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
![](../assets/dev-branch.png) | ||
![](../assets/dev-branch-name.png) | ||
|
||
In this new branch, we are going to edit the `setup_phantom` function located in the file `src/ui/ExportUIFunctions.jl`. Specifically, we will replace the line where a brain phantom is defined with the function `pelvis_brain2D`: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I believe this should be pelvis_phantom2D
instead of pelvis_brain2D
.
In this new branch, we are going to edit the `setup_phantom` function located in the file `src/ui/ExportUIFunctions.jl`. Specifically, we will replace the line where a brain phantom is defined with the function `pelvis_brain2D`: | |
In this new branch, we are going to edit the `setup_phantom` function located in the file `src/ui/ExportUIFunctions.jl`. Specifically, we will replace the line where a brain phantom is defined with the function `pelvis_phantom2D`: |
```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 then open VSCode and navigate to this folder; it should look like this: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I actually encountered an error when I ran this:
(@v1.10) pkg> dev https://github.com/JanWP/KomaMRI.jl
Cloning git-repo `https://github.com/JanWP/KomaMRI.jl`
Resolving package versions...
ERROR: Unsatisfiable requirements detected for package KomaMRICore [4baa4f4d]:
KomaMRICore [4baa4f4d] log:
├─possible versions are: 0.7.4-0.8.3 or uninstalled
└─restricted to versions 0.9 by KomaMRI [6a340f8b] — no versions left
└─KomaMRI [6a340f8b] log:
├─possible versions are: 0.9.0 or uninstalled
└─KomaMRI [6a340f8b] is fixed to version 0.9.0-DEV
However, I was able to follow the rest of the instructions just fine, since all that is needed at this stage is to get the source code checked out in to the Julia dev directory. Maybe the same could be achieved without error using a git checkout
, or a comment could be added to let the reader know that this error can be safely ignored.
Secondly, should the text remind inexperienced users to check they have set up their anonymous GitHub email address for the local repository? Otherwise push may fail later if they opted to keep their email address private in their GitHub settings.
```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 then open VSCode and navigate to this folder; it should look like this: | |
```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 may get an error regarding unsatisfiable requirements, due to the naming of the development verion of KomaMRI packages (e.g. 0.9.0-DEV). You can ignore the error for now, instructions on how to correctly set up the Julia environment are below. | |
If you have configured your GitHub account to keep your email address private, make sure, you use your private GitHub email (`<github-username>@users.noreply.github.com`) in your local Git repository. Otherwise GitHub will not allow you to push your local commits to GitHub. To check the current setting for your email: | |
```bash | |
user@machine:~/.julia/dev/KomaMRI$ git config user.email | |
``` | |
You can modify the setting in the following way (make sure to replace `<github-username>` with your GitHub username): | |
```bash | |
user@machine:~/.julia/dev/KomaMRI$ git config user.email <github-username>@users.noreply.github.com | |
``` | |
You can then open VSCode and navigate to this folder; it should look like this: |
https://juliahealth.org/KomaMRI.jl/previews/PR382/