From 3b23dea65979d21adfc3e4f0e71154e210ece3ee Mon Sep 17 00:00:00 2001 From: Paula-Kli Date: Tue, 10 Oct 2023 10:49:38 +0200 Subject: [PATCH] fix: Move git documentation to tools --- .../docs/getting-started/working-with-git.md | 278 ------------------ .../docs/tools/capella/working-with-git.md | 131 ++++++++- 2 files changed, 126 insertions(+), 283 deletions(-) delete mode 100644 docs/user/docs/getting-started/working-with-git.md diff --git a/docs/user/docs/getting-started/working-with-git.md b/docs/user/docs/getting-started/working-with-git.md deleted file mode 100644 index 256b7d71d9..0000000000 --- a/docs/user/docs/getting-started/working-with-git.md +++ /dev/null @@ -1,278 +0,0 @@ - - -# Working with Git - -In this guide we explain how to use Git via Eclipse. When using Git we make -changes _locally_ and push them to a _remote_ (Gitlab or Github mainly) -repository. Here we explain how to get made changes to the remote repository so -that collegues can see and review them. - -## Clone a Repository - -First open the View _Git Repository_ by clicking on the magnifying glass (1) in -the right corner. - -![Step 1: Open View Search](working-with-git/search-view.png) - -Searching looks like: - -![Step 2: Search for View](working-with-git/search-git-repository-view.png) - -When clicking "Clone a Git repository" a view "Source Git Repository" to enter -the repository url opens. Enter here the URL of the _Remote_ of your repository -and if it is not a public repository enter your username and password. After -clicking "Next" the "Branch Selection" opens. Here you can pick a branch on -which you want to work. After clicking "Next" another time, the view "Local -Destination" opens. This shows where your work is going to be stored locally. - - - -!!! info Tick the box: "Import all existing Eclipse projects after clone -finishes" importing the cloned repository into your eclipse workspace - -![Step 3: Local Destination](working-with-git/local-destination.png) - -Then you can click finish. Your repository from the _Remote_ is now cloned -locally. - -## Switch Branches - -To collaborate it might be useful to work on different branches. Therefore, -there are two ways to switch branches (to checkout existing ones or to create a -new one). - -Either you right click on the project name in the lower right corner, go to -"Switch to" and then e.g. "New Branch" - -![Step 4: Search for View](working-with-git/switch-branch-v1.png) - -or you can right click on the project name in the project tree and then click -"Team"> "Switch to" > "New Branch". - -![Step 5: Search for View](working-with-git/switch-branch-v2.png) - -In order to make the changes visible in your project tree and to see on which -branch you are currently working on right click on the project name > "Close -Project" and then open the project again. - -## Prepare to Commit - Stage changes - -In Git staged changes are saved changes that we mark to use in our next commit. - -In order to stage changes in Eclipse, open the View: _Git Staging_. In that -view you can see the staged and the unstaged changes (1). You can also see -changes that you made in the file tree on the left indicated by ">" (2). If -there are no (un-)staged changes you did not make a change compared to the last -state that Git already has saved in commits. - -![Step 6: Search for View](working-with-git/unstaged-changes.png) - -In the _Git Staging_ View mark the unstaged files that you want to stage and -drag them with your mouse to the "Staged Changes" area. Then reload (3) the -View in order to see the made changes. - -## Commit and Push Changes - -After having staged the changes they should be put into a commit. Therefore, -type a commit message to show what changes have been made. A commit message can -look like: - -``` -Short summary of the changes - -Details of the made changes -Change #1 -Change #2 -``` - -Thus you and your collegues know what happened in the commit. Then commit the -changes (2). - - -!!! info - The commit is now made locally. In order to publish it and share it with other you have to push it to the *Remote*! - -![Step 7: Search for View](working-with-git/staged-changes.png) - -If you already committed your changes you can right click on the Project > -"Team" > "Push to Origin" in order to push your changes to the remote. - -If you have not commited yet and want to publish your changes and to share them -with your team rather click: "Commit and Push" (1). If you have not configured -that before you are now asked to "Configure upstream for push and pull" and the -selected default of "Merge" can just be kept. You might now be asked to enter a -user and a password for the remote repository in order to push your changes -there. Having done that you can click "Push". - -Now your changes are saved at the remote repository where they are not lost and -your collegues can see them. - -## Diff and Merge Models - - -!!! warning - If you have to merge due to a merge conflict do not commit unless all conflicts highlighted are solved. - -If the merge tool is not opening on its own due to a merge conflict you can -also diff two models on your own in order to check which changes were made. - -Therefore, select both `.aird`-files (e.g. with control click). Then right -click on one of the files and select "Compare with" > "Each other as model". - -![Open compare View](working-with-git/start-compare-view.png) - -In the image you can see the -[coffee machine model](https://github.com/DSD-DBS/coffee-machine) imported -twice with different changes made to each model in order to compare them. - -In the View "Define the comparison operation to perform" it is important to -choose the **correct** order of which model is the source and which one is the -target. In that case we are taking the changes in the source to apply them to -the target, and are going to change the target model. - - -!!! warning - Make sure to select the correct direction of merging in order to modify the - correct model. - -![Configure Merge Direction](working-with-git/configure-merge-direction.png) - -In the example we want to merge our changes from Left (coffee-machine model on -working branch) into Right (coffee machine model on main branch)(1). - -Afterwards click "Configure" (2) to make further configurations. - -Choose the option "Transfer of elements between models created independently". -Then click "Show advanced settings >>" to configure the matching process -between elements. Thus, click the now appeared tab "Matching". - -Usually the UUIDs of the objects in your model should be stable. So ticking the -Absolute criteria "Technical IDs" and "Property IDs" should be sufficient. -Especially for if you know that there could be changes in diagrams you might -also want to tick "Diagrams: Match shapes according to represented elements" -and "Diagrams: Match remaining shapes according to type" as in Diagrams IDs -might change just by opening them. If you are unsure whether your IDs are -stable the option "Capella: Match equivalent technical elements" also worked in -the past. If nothing else helps choose "Names" and click "Use labels as names" -to match but labels easily change. - -![Configure Matching Strategie](working-with-git/configure-merge-matching.png) - -Afterwards, click "Ok" and "Finish". - -Then you get into the merge view. Marked with the lock you can see which model -is going to be modified. They are also labeled as source and target where the -source is from which we are taking the changes and the target is the model that -gets modified. - -![Explain Merge View](working-with-git/explain-merge-view.png) - -The colors highlight what change was made and will be applied to the target if -you apply the change: _blue: create, red: delete, purple: modify_. - -If there are any objects that are overarching you have to merge them seperately -as they can not be merged in the seperate layers. - -### Merge Model Elements - -In the synthesis view you can see the number of changes that happened. If you -click on a specific change you can see in the Details (1) and also marked in -blue on both models what changed and possibly how the current status in both -models is. Then you can right click on the change in the synthesis view and -click "Apply change(s)" (2) and you can click "Ok" then. Afterwards make sure -to Ctrl+S or File > Save to save the change made. - - -!!! warning - - If any of your changes depend on common objects independent of layers make sure - to also apply those changes in order to create a working modification of the - model. - -If you have also changes in diagrams you should migrate them as well in the -same session. - -### Merge Diagrams - -Diagrams are stored in the `.aird` file. There the application of changes -happens similar. You can have a look into the multiple stages to see the what -exactly changed in the diagrams and you can very detailed choose the changes -that you want to apply. - -If you have also changes in the model content you should merge both in the same -session. - -## Merge Conflicts - -Commit your changes as described above. Pull from the remote (e.g. right click -on the project > "Team" > "Pull"). This might result in merge conflicts which -you can solve via the merge tool. - -### Merging with the Merge Tool - -In the above description we made sure to decide which model is our target and -is going to be modified while the changes would be taken from the source model. -In the case of a merge conflict we have changes in both models at the same -position and it is not possible to decide which change to keep and which to -delete while possibly both are reasonable changes. Thus we as users have to -decide that and both changes have the same right to be present in the model. In -order to not just apply changes you can decide from which sides changes can be -taken. - -![Decide Side of Change](working-with-git/merge-decide-side.png) - -With the butttons above the details of the made changes enable us to decide the -change from which model to take and which change to discard. - -If the number of changes is overwhelming you can filter them by different -criteria (2). In the category "Three-way" you can tick "filtered" for the -changes that for the moment you prefer not to see and to tackle to apply the -changes one after another. - -Make sure to resolve all conflicts before commiting! After merging reopen the -model and look especially into layouting as capella might be a bit -opportunistic in merging layouts. - -### Merging if Merge Tool is not possible - -If merging with the merge tool is not possible you have to open the reset view. - -![Step 8: Open Reset View](working-with-git/open-reset-view.png) - -Then select hard reset of your local branch - -![Step 9: Git Reset Hard](working-with-git/reset-hard-view.png) - -If you committed your changes earlier, and select your local main branch as -described, your local files will be reset to the state they were in after your -**last local commit**. This way, you drop the changes from the server locally, -but keep your changes. Removing the changes from the server in your local main -branch is not a problem, because they are still present in the remote main -branch on the git server. - -You should now be able to see the project again with all changes, you -performed. Now you should push your local changes to a new branch. To do so, -right click on the project > "Team" > "Push branch 'main'...". In the view -"Push to branch in remote" you should enter an intermediate branch name like -“merge-branch-name” (1) and remove the “configure upstream push and pull” (2) -option. - -![Step 10: Git Create Intermediate Branch](working-with-git/create-merge-branch.png) - -After pushing your changes to the remote Git repository, open the remote -project on Gitlab or Github. Then open a Merge request (Gitlab) or Pull request -(Github) respectively and try merging your "merge-branch-name" branch into main -(or the branch you wanted to push on before). - -You will now see whether the Merge request/ Pull request can be merged -automatically or not - -1. It can be merged automatically: Go for it and merge it. To continue working - on the model, we recommend using a new clean session of Capella. -1. I it can’t be merged automatically: You have now two options: - 1. Redo your work. We recommend using a new session for that - 1. Open a service request or contact the operations team in order to try to - get your changes merged manually. diff --git a/docs/user/docs/tools/capella/working-with-git.md b/docs/user/docs/tools/capella/working-with-git.md index 5173150dc2..021d6a5166 100644 --- a/docs/user/docs/tools/capella/working-with-git.md +++ b/docs/user/docs/tools/capella/working-with-git.md @@ -28,7 +28,7 @@ clicking "Next" the "Branch Selection" opens. Here you can pick a branch on which you want to work. After clicking "Next" another time, the view "Local Destination" opens. This shows where your work is going to be stored locally. - + !!! info @@ -99,7 +99,6 @@ changes (2). ![Step 7: Search for View](working-with-git/staged-changes.png) - If you already committed your changes you can right click on the Project > "Team" > "Push to Origin" in order to push your changes to the remote. @@ -113,17 +112,139 @@ there. Having done that you can click "Push". Now your changes are saved at the remote repository where they are not lost and your collegues can see them. +## Diff and Merge Models + + +!!! warning + If you have to merge due to a merge conflict do not commit unless all conflicts highlighted are solved. + +If the merge tool is not opening on its own due to a merge conflict you can +also diff two models on your own in order to check which changes were made. + +Therefore, select both `.aird`-files (e.g. with control click). Then right +click on one of the files and select "Compare with" > "Each other as model". + +![Open compare View](working-with-git/start-compare-view.png) + +In the image you can see the +[coffee machine model](https://github.com/DSD-DBS/coffee-machine) imported +twice with different changes made to each model in order to compare them. + +In the View "Define the comparison operation to perform" it is important to +choose the **correct** order of which model is the source and which one is the +target. In that case we are taking the changes in the source to apply them to +the target, and are going to change the target model. + + +!!! warning + Make sure to select the correct direction of merging in order to modify the + correct model. + +![Configure Merge Direction](working-with-git/configure-merge-direction.png) + +In the example we want to merge our changes from Left (coffee-machine model on +working branch) into Right (coffee machine model on main branch)(1). + +Afterwards click "Configure" (2) to make further configurations. + +Choose the option "Transfer of elements between models created independently". +Then click "Show advanced settings >>" to configure the matching process +between elements. Thus, click the now appeared tab "Matching". + +Usually the UUIDs of the objects in your model should be stable. So ticking the +Absolute criteria "Technical IDs" and "Property IDs" should be sufficient. +Especially for if you know that there could be changes in diagrams you might +also want to tick "Diagrams: Match shapes according to represented elements" +and "Diagrams: Match remaining shapes according to type" as in Diagrams IDs +might change just by opening them. If you are unsure whether your IDs are +stable the option "Capella: Match equivalent technical elements" also worked in +the past. If nothing else helps choose "Names" and click "Use labels as names" +to match but labels easily change. + +![Configure Matching Strategie](working-with-git/configure-merge-matching.png) + +Afterwards, click "Ok" and "Finish". + +Then you get into the merge view. Marked with the lock you can see which model +is going to be modified. They are also labeled as source and target where the +source is from which we are taking the changes and the target is the model that +gets modified. + +![Explain Merge View](working-with-git/explain-merge-view.png) + +The colors highlight what change was made and will be applied to the target if +you apply the change: _blue: create, red: delete, purple: modify_. + +If there are any objects that are overarching you have to merge them seperately +as they can not be merged in the seperate layers. + +### Merge Model Elements + +In the synthesis view you can see the number of changes that happened. If you +click on a specific change you can see in the Details (1) and also marked in +blue on both models what changed and possibly how the current status in both +models is. Then you can right click on the change in the synthesis view and +click "Apply change(s)" (2) and you can click "Ok" then. Afterwards make sure +to Ctrl+S or File > Save to save the change made. + + +!!! warning + + If any of your changes depend on common objects independent of layers make sure + to also apply those changes in order to create a working modification of the + model. + +If you have also changes in diagrams you should migrate them as well in the +same session. + +### Merge Diagrams + +Diagrams are stored in the `.aird` file. There the application of changes +happens similar. You can have a look into the multiple stages to see the what +exactly changed in the diagrams and you can very detailed choose the changes +that you want to apply. + +If you have also changes in the model content you should merge both in the same +session. + ## Merge Conflicts Commit your changes as described above. Pull from the remote (e.g. right click on the project > "Team" > "Pull"). This might result in merge conflicts which you can solve via the merge tool. -If this is not the case you have to open the reset view. +### Merging with the Merge Tool + +In the above description we made sure to decide which model is our target and +is going to be modified while the changes would be taken from the source model. +In the case of a merge conflict we have changes in both models at the same +position and it is not possible to decide which change to keep and which to +delete while possibly both are reasonable changes. Thus we as users have to +decide that and both changes have the same right to be present in the model. In +order to not just apply changes you can decide from which sides changes can be +taken. + +![Decide Side of Change](working-with-git/merge-decide-side.png) + +With the butttons above the details of the made changes enable us to decide the +change from which model to take and which change to discard. + +If the number of changes is overwhelming you can filter them by different +criteria (2). In the category "Three-way" you can tick "filtered" for the +changes that for the moment you prefer not to see and to tackle to apply the +changes one after another. + +Make sure to resolve all conflicts before commiting! After merging reopen the +model and look especially into layouting as capella might be a bit +opportunistic in merging layouts. + +### Merging if Merge Tool is not possible + +If merging with the merge tool is not possible you have to open the reset view. ![Step 8: Open Reset View](working-with-git/open-reset-view.png) -Then select hard reset of your local branch: +Then select hard reset of your local branch ![Step 9: Git Reset Hard](working-with-git/reset-hard-view.png) @@ -149,7 +270,7 @@ project on Gitlab or Github. Then open a Merge request (Gitlab) or Pull request (or the branch you wanted to push on before). You will now see whether the Merge request/ Pull request can be merged -automatically or not: +automatically or not 1. It can be merged automatically: Go for it and merge it. To continue working