diff --git a/source/coding/git.rst b/source/coding/git.rst index 74151da..82ce377 100644 --- a/source/coding/git.rst +++ b/source/coding/git.rst @@ -32,7 +32,7 @@ The goal will be to work on your computer and save your changes to **your** fork By default all repositories have a main version of the code (a branch called *master* or *main*). When you are exploring new pieces of code, fixing bugs or tinkering in general you should always create a branch first (with a meaningful name) to avoid messing up your main branch with your tests :bash:`git checkout -b my_branch`. Your main branch in **your** fork should always stay the same as the main branch in the **upstream**. A good practice is to never use :bash:`git add` or :bash:`git commit` in your main branch: only :bash:`git pull upstream master` (or main). -If your modifications are useful, and you want to keep it safe, you should commit and push them. If your modifications of one branch of your own fork to be added to the real scilpy repository (upstream)could be useful to everyone and you want to share them with the rest of the world [2]_, you should consider doing a *pull request*. Only when everything is clean and tested, in the Github web interface, you can start an official pull request that will be reviewed by other members of the lab. +If your modifications are useful, and you want to keep it safe, you should commit and push them. If your modifications of one branch of your own fork to be added to the real scilpy repository (upstream) could be useful to everyone and you want to share them with the rest of the world [2]_, you should consider doing a *pull request*. Only when everything is clean and tested, in the Github web interface, you can start an official pull request that will be reviewed by other members of the lab. When that branch is accepted and merged to the master branch of the upstream, then if you update **your** own master branch of **your** fork (:bash:`git pull upstream master`), you will see the changes. You will then be able to delete safely your branch in your fork (:bash:`git branch -d my_test_branch`). diff --git a/source/guides/git.rst b/source/guides/git.rst index e68a4da..5ed819e 100644 --- a/source/guides/git.rst +++ b/source/guides/git.rst @@ -14,153 +14,117 @@ For example, you're trying to develop a feature on Scilpy and your collegue is d You can find many good tutorials on internet, such as `this one `_ on the official website. Or check `this very nice introduction `_ by Alex from our lab. - -Summary of git commands ------------------------ - -Here is a figure [1]_ with a summary of the commands that might be useful, but you can google for more information. Every action happening inside the cloud (on internet) isn't performed in command line, but with buttons on Github. Inversely, every action concerning your local computer is performed in command-line. - -Here a list of one-line summary for Git commands (make sure you find them on Figure 1) - - :bash:`git clone`: Create a local copy of a remote repository. - - :bash:`git checkout`: Switch to a specific branch or commit. - - :bash:`git log`: Display the commit history in the repository. - - :bash:`git status`: Show the current state of your working directory, including changes staged, modified, or untracked. - - :bash:`git stash`: Temporarily save uncommitted changes for later use. - - :bash:`git add`: Stage changes in your working directory for the next commit. - - :bash:`git commit`: Record changes made to the repo with a description. - - :bash:`git push`: Send your local commits to a remote repository. - - :bash:`git pull`: Retrieve changes from a remote repository and merge them into your current branch. - - :bash:`git fetch`: Retrieve updates from a remote repository without merging them into your current branch. - - :bash:`git merge`: Combine the changes from one branch into another. - - :bash:`git rebase`: Reapply commits from one branch onto another, linearizing history. - - :bash:`git remote`: Manage the list of remote repositories connected to your local repo. +**The following sections take Scilpy as an example, but can be applied to any repositories on Github.** +For users +--------- -Here a list of one-line summary for Git concepts (make sure you find them on Figure 1) - - *a branch*: A parallel line of development in a repository. - - *a commit*: A snapshot of the changes made to a repo, with a unique identifier and message. - - *master/main*: The default primary branch in a Git repository, containing the latest stable version. - - *origin*: The default name for the remote repository from which you cloned. - - *a fork*: A copy of a repository, allowing you to make changes without affecting the original. - - *upstream*: The original repository that a fork is based on, used to track changes from the original. - - *hash*: A unique, fixed-length identifier generated from the content of a commit, ensuring data integrity. - - *history*: The chronological sequence of commits in a repository, representing the evolution of a project. - - *conflict*: A situation that occurs when two or more branches have conflicting changes to the same part of a file, requiring manual resolution. - - *delta*: The difference between two sets of file contents, often used to represent changes between commits or branches. +*This section targets users who don't plan on developing code.* -.. figure:: /images/intro_to_git_organization.png - :scale: 25 % +.. figure:: /images/intro_to_git_link.png + :scale: 55 % :align: right -In Git, your working directory is the local folder containing the current state of your project files. As you make changes to these files, they are tracked by Git but not yet committed (see :bash:`git status`). +You can download a repository; we say to **clone** a repository. Downloading vs cloning: when you download, it takes the code as it is then, wraps it in a zip file and downloads it all. But then, you have nothing telling you where you downloaded it from and you can't update the code. Cloning keeps the link with reference online repository and allows you to update either your local code (offline) or change the Github code (online). You will need to open a terminal and use the clone command (find the link by clicking on Github's green button *Code*): :bash:`git clone INSERT_LINK_TO_THE_REPOSITORY_TO_CLONE` -The staging area, also known as the index, is an intermediate space where you can organize and prepare the changes you want to include in your next commit (see :bash:`git add`). By adding changes to the staging area, you're essentially telling Git which changes should be recorded in the upcoming commit (see :bash:`git commit`). Your local repository is the hidden .git folder within your working directory, where Git stores the entire version history, including all commits and branches. It is separate from the working directory, ensuring that your project's history is preserved even if you make changes or delete files in your working directory. +Once cloned we recommend you to work with a stable version of the code. Often, programmers will separate their most recent (less tested) code from more stable versions by adding tags (releases) to the various versions. To use a specific version / tag / release, use :bash:`git checkout VERSION`. We expect users to remember which repository they cloned, to put the code in a appropriate folder on their computer (and know where it is), approximately when they cloned it and to remember that Scilpy constantly evolve. -A remote repository is a version of your project stored on a remote server, allowing for collaboration with other developers. You can push your local commits (see :bash:`git push`) to the remote repository and pull changes made by others (see :bash:`git pull` or :bash:`git fetch`), keeping your project in sync across multiple environments. +If there is a bug when using the code, make sure to read the documentation, ask developers for help and if it is a real problem, raise an issue on Github. -Setting up everything the first time ------------------------------------- -More details specific to Scilpy and how we use Git in the Lab is available :doc:`here <../coding/git>`. +For developers +--------------- -.. figure:: /images/intro_to_git_link.png - :scale: 50 % +*This section targets developers who plan on developing code.* + +.. image:: /images/git_in_the_lab_remotes.png + :scale: 25 % :align: right -.. code-block:: bash +Let's say you want to develop Scilpy. Instead of cloning Scilpy directly on your computer, you should **fork** it, i.e. copy it as one of your own repositories in your own account. On Github, you can find the button *fork* on the top right of Scilpy's repository page. Then, you can clone this copy of the repository on your computer (find the link by clicking on Github's green button *Code*): :bash:`git clone INSERT_LINK_TO_YOUR_FORKED_REPOSITORY` - # Cloning the code - git clone ${link_to_my_fork} - cd my_fork/ +The goal will be to work on your computer and save regularly your changes to **your** fork (it will automatically be named origin). We recommend immediately going inside the cloned folder (:bash:`cd scilpy` in this case) and setting up a remote named *upstream* to help link your fork to the original repository [1]_: :bash:`git remote add upstream git@github.com:scilus/scilpy.git` - # Telling git who are the upstream and origin - git remote add upstream ${link_to_upstream} - git remote add origin ${link_to_my_fork} # Should be set automatically - git remote -v # To verify everything. +By default all repositories have a main version of the code (a branch called *master* or *main*). When you are exploring new pieces of code, fixing bugs or tinkering in general you should always create a branch first (with a meaningful name) to avoid messing up your main branch with your tests: :bash:`git checkout -b my_branch` - # Creating branches - git branch my_branch_1 # create it - git checkout my_branch_1 # switch on it - git checkout -b my_branch_2 # create AND switch - # Note that here, my_branch_2 would be a copy of my_branch_1. - # If instead you want to start from the master, switch to your master branch first. +Your main branch in **your** fork should always stay the same as the main branch in the **upstream**. A good practice is to never use :bash:`git add` or :bash:`git commit` in your main branch, only :bash:`git pull upstream master` (or main). - # Delete a branch: - git branch -d my_branch # For a local branch - git push origin --delete my_branch # For a branch on origin +When working in a branch other than the main one (*master* or *main*), you should often save (update) your modifications online. Each update is called a **commit**. First, to see which files have been modified without telling Git, use :bash:`git status`. Then, to add or update a file in Git's memory, use :bash:`git add my_file`. You can also add all files that have been modified and that Git already knew about, with :bash:`git add -u`. If you check again with :bash:`git status`, everything in green will be recorded with the next command: :bash:`git commit -m "Message to explain the work I have been doing in this update"`. To send these changes to the same branch name in your forked repository, use :bash:`git push origin my_branch`. -Merging branches -^^^^^^^^^^^^^^^^ +If your modifications are useful, and you want to keep it safe, you should commit and push them. If your modifications of one branch of your own fork to be added to the real scilpy repository (upstream) could be useful to everyone and you want to share them with the rest of the world [2]_, you should consider doing a *pull request*. Only when everything is clean and tested, in the Github web interface, you can start an official pull request that will be reviewed by other members of the lab. -Merging branch is a crucial concept in collaborative projects, Figure 3 shows how it affect history [3]_. +When that branch is accepted and merged to the master branch of the upstream, then if you update **your** own master branch of **your** fork (:bash:`git pull upstream master`), you will see the changes. You will then be able to delete safely your branch in your fork (:bash:`git branch -d my_test_branch`). -.. figure:: /images/intro_to_git_merge_rebase_history.png - :scale: 80 % - :align: right +Every time you create a branch, be sure you checkout (your fork) master (:bash:`git checkout master`), then update your master with what is new *upstream* (:bash:`git pull upstream master`), finally create your branch (:bash:`git checkout -b my_branch`). This way, you will always start developing with fresh code that is up to date, this avoid conflicts and working on an already solved issue, for example. Moreover, while you develop your part of code on your branch, you might want to update the code with the latest *upstream* version. First go back to master (:bash:`git checkout master`) and update it with the *upstream* version (:bash:`git pull upstream master`). Then, go back to your branch (:bash:`git checkout my_branch`) and update it with the new *origin* version (:bash:`git pull origin master`). -.. code-block:: bash - # Technique 1: merge. To merge branch_2 (pink) into branch_1 (yellow): - git checkout branch_1 - git merge branch_2 +For reviewers +------------- - # Technique 2: rebase - git rebase branch_1 branch_2 - # P.S. If you then want to push your branch (git push origin branch_2), git won't - # recognize your branch's history and won't allow it. Use: - git push --force origin branch_2 +*This section targets reviewers who plan on reviewing code.* -Updating your code -^^^^^^^^^^^^^^^^^^ +.. figure:: /images/git_in_the_lab_tests.png + :scale: 65 % + :align: right -.. code-block:: bash +Every once in a while you are expected to review the code of someone else. For a one time review you can **fetch** the code from *upstream* with: :bash:`git fetch upstream pull/${PR_NUMBER}/head:${DESIRED_BRANCH_NAME}` - # From the origin to both your local repo and your workspace: - git pull origin master # master or any branch you want to update. - # Note that this is equivalent to git fetch + git merge. +However, if you review a lot we recommend adding the author of the pull request (PR) as a remote, fetch the branch and checkout the code (to do every time the code changes in the pull request if multiple reviews are needed). - # From the upstream to your local repo - git pull upstream master +A few things to considering when reviewing someone else code: + - The tests are expected to work, at the bottom of the PR (see Figure to the right) + - Read the documentation (argparser, docstring, comments), it should be clear for non-experts + - All changes should be needed for the bug fix or features, no modification outside of the scope of the PR + - Fix conflicts if there is any, merge/rebase with master + - Test it yourself to make sure you understand the change and that it works as expected + - Be critical of the code speed, robustness, readability, etc. + - If the PR is out of your expertise, make sure to tag someone that can help with the review - # From the upstream to your forked repo - # There is no way to do this direclty. You can update your local repo and - # send the update back up to your forked repo - git push origin master - # Updating one branch on your computer with the updates from the master: - # Update master. Then: - git rebase master my_branch +Git commands +------------ +Here a list of one-line summary for Git commands + - :bash:`git clone`: Create a local copy of a remote repository. + - :bash:`git checkout`: Switch to a specific branch or commit. + - :bash:`git branch`: Create a new branch. + - :bash:`git log`: Display the commit history in the repository. + - :bash:`git status`: Show the current state of your working directory, including changes staged, modified, or untracked. + - :bash:`git stash`: Temporarily save uncommitted changes for later use. + - :bash:`git add`: Stage changes in your working directory for the next commit. + - :bash:`git commit`: Record changes made to the repo with a description. + - :bash:`git push`: Send your local commits to a remote repository. + - :bash:`git pull`: Retrieve changes from a remote repository and merge them into your current branch. + - :bash:`git fetch`: Retrieve updates from a remote repository without merging them into your current branch. + - :bash:`git merge`: Combine the changes from one branch into another. + - :bash:`git rebase`: Reapply commits from one branch onto another, linearizing history. + - :bash:`git remote`: Manage the list of remote repositories connected to your local repo. -Keeping your code safe -^^^^^^^^^^^^^^^^^^^^^^ +Here a list of one-line summary for Git concepts + - *a branch*: A parallel line of development in a repository. + - *a commit*: A snapshot of the changes made to a repo, with a unique identifier and message. + - *master/main*: The default primary branch in a Git repository, containing the latest stable version. + - *origin*: The default name for the remote repository from which you cloned. + - *a fork*: A copy of a repository, allowing you to make changes without affecting the original. + - *upstream*: The original repository that a fork is based on, used to track changes from the original. + - *hash*: A unique, fixed-length identifier generated from the content of a commit, ensuring data integrity. + - *history*: The chronological sequence of commits in a repository, representing the evolution of a project. + - *conflict*: A situation that occurs when two or more branches have conflicting changes to the same part of a file, requiring manual resolution. + - *delta*: The difference between two sets of file contents, often used to represent changes between commits or branches. -.. figure:: /images/intro_to_git_tree.png - :scale: 80 % +.. figure:: /images/intro_to_git_organization.png + :scale: 25 % :align: right -Each update is called a **commit**. This is shown in the second figure [2]_. - -.. code-block:: bash - - # From the workspace to your local repo: - git status # To see which files have been modified without telling git - git add my_file # To add or update a file in git's memory. - git add -u # To add all files that have been modified, but that git already knew - git status # If you check again, everything in green will be recorded with the next command: - git commit -m "Message to explain the work I have been doing in this update" +Here is a figure [1]_ with a summary of the commands that might be useful, but you can google for more information. Every action happening inside the cloud (on internet) isn't performed in command line, but with buttons on Github. Inversely, every action concerning your local computer is performed in command-line. - # From the local repo to your forked repo - git push origin my_branch # Will automatically send it to the same branch name in your forked repo. +In Git, your working directory is the local folder containing the current state of your project files. As you make changes to these files, they are tracked by Git but not yet committed (see :bash:`git status`). - # From your forked repo to the upstream repo: - # Use the Pull Request button on internet +The staging area, also known as the index, is an intermediate space where you can organize and prepare the changes you want to include in your next commit (see :bash:`git add`). By adding changes to the staging area, you're essentially telling Git which changes should be recorded in the upcoming commit (see :bash:`git commit`). Your local repository is the hidden .git folder within your working directory, where Git stores the entire version history, including all commits and branches. It is separate from the working directory, ensuring that your project's history is preserved even if you make changes or delete files in your working directory. - # From your local repo to the upstream repo: - # DON'T DO THAT. Didn't you see that there is no such arrow on Figure 1! +A remote repository is a version of your project stored on a remote server, allowing for collaboration with other developers. You can push your local commits (see :bash:`git push`) to the remote repository and pull changes made by others (see :bash:`git pull` or :bash:`git fetch`), keeping your project in sync across multiple environments. .. [1] Modified from: https://github.com/sf-wdi-21/notes/blob/master/how-tos/github-workflow.md -.. [2] Adapted from: https://medium.com/tech-and-the-city/changing-a-super-old-git-commit-history-20346f709ca9 -.. [3] Taken from: http://www.differencebetween.net/technology/difference-between-git-rebase-and-merge/ \ No newline at end of file +.. [2] Taken from: https://buddy.works/blog/5-types-of-git-workflows \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index b526146..5868836 100644 --- a/source/index.rst +++ b/source/index.rst @@ -48,15 +48,6 @@ Here, you will find a summary of the tools we develop, and some clues on how we guides/code_with_nextflow guides/anatomy -.. toctree:: - :maxdepth: 1 - :caption: Coding standards in the lab - - coding/python - coding/scilpy - coding/git - - .. toctree:: :maxdepth: 1 :caption: Dealing with heavy data