=============================================== Creating and administrating a forked repository =============================================== .. warning:: Only team leaders should create forks for their repositories. Each team should create one fork. 1. Creation of a new fork repository ==================================== A. Accessing the upstream repository ------------------------------------ As presented in the `GIT&GitLab Workflow Documentation` file, to work in the project a fork needs to be created from the upstream repository. In the main GitLab page, navigate on the bottom of the page to the **Public projects** (:numref:`fig11`) section (Browse projects), then click **All** and all the public repositories will be shown (:numref:`fig12`): .. _fig11: .. figure:: images/3CreatingAdministrating/Picture10.png Initial main window .. _fig12: .. figure:: images/3CreatingAdministrating/Picture11.png Public projects For the following scenario, the repository that will be used is named **STEPlib-DEMO**. It must be noted that this repository is stored in the creator’s folder. In this case, the Master user is Jonathan Bernales and the project is named STEPlib-DEMO. To access the repository, simply click on it and the following interface will be shown: .. _fig13: .. figure:: images/3CreatingAdministrating/Picture12.png Main GitLab UPSTREAM project interface B. Forking the repository ------------------------- To fork the project, simply click on the fork button next to the project URL as seen in :numref:`fig13`. GitLab will then ask you to which users the project shall be forked. Simply select your user and the server will automatically fork the repository: .. figure:: images/3CreatingAdministrating/Picture13.png Forking the project for a team leader Once the project is forked, a confirmation ribbon will appear and you will be redirected to your forked repository: .. _fig15: .. figure:: images/3CreatingAdministrating/Picture14.png Forked repository interface A couple of points need to be detailed: * As it can be seen in the top-left corner of this figure, the repository is now located in the user who forked the upstream. * The user who forked the upstream repository is now master of their fork, meaning they can completely manage and customize the fork. * GitLab still knows from which project this repository has been forked from. If this process has gone smoothly, when logging in to GitLab and navigating to **Your projects** the new forked repository should appear: .. figure:: images/3CreatingAdministrating/Picture15.png Project result after forking * Jean Brange / STEPlib-DEMO is the **forked** repository * Jonathan Bernales / STEPlib-DEMO is the **upstream** repository 2. Managing the forked repository ================================= A. Managing user privileges and project name -------------------------------------------- Since you now have the Master access rights in the forked repository, different options become available. Since the fork is a copy of the upstream repository, all the project attributes are also copied except for user rights. The only user that will have access to the forked repository will be the one that will have made the fork procedure. These options are available in the top-right menu in the project window: .. _fig17: .. figure:: images/3CreatingAdministrating/Picture16.png Project options menu In this scenario we will cange the forked repository name to a more clear name. In this case “FORK-AP242â€. To do so, click on **Settings->General** in the project menu (:numref:`fig17`). The changes should be done in the **Project name** and the **Path** fields in the **Rename repository** section scrolling down. The following window will appear: .. _fig18: .. figure:: images/3CreatingAdministrating/Picture17.png Project settings Different attributes can be changed such as the project visibility. If this value is set to “Internal†then every logged in user will be able to see and clone the project. If you scroll down you will find the “Rename repository†section and you will be able to rename the path. To allow users to have access to the forked repository, access the project menu (:numref:`fig17`) and select **Members**. The following window will appear: .. figure:: images/3CreatingAdministrating/Picture18.png Project "members" menu In the first field, simply write the user to which you wish to grant access. Role permissions details can be found `here`_. .. _here: http://git2.boost-lab.net/help/user/permissions B. Creating the team custom project branch ------------------------------------------ By default, the upstream repository will have 3 branches that will be “masterâ€, “dev†and “releaseâ€. As described in the workflow description document, these branches will be infinite and will never be closed. For each new developed feature (Change Request or project), a new branch should be created in the forked repository so each developer can work freely without polluting the “dev†branch. To create a new branch, navigate to the **Repository** tab and select **Branches** (:numref:`fig13`). Clicking on the **New Branch** button will show a window in which the new branch name should be indicated: .. figure:: images/3CreatingAdministrating/Picture19.png GitLab project Branches menu The new project branch should be created from the dev branch and have a clear name: .. figure:: images/3CreatingAdministrating/Picture20.png Branch creation 3 Cloning the forked repository =============================== A. Cloning the forked repository and it's branches -------------------------------------------------- Through this section, we will present the process of cloning the forked repository locally allowing us to start working with the development. The EGit Eclipse plugin will be used to illustrate the following scenario. Multiple GIT GUI clients exist, the most popular being GIT Kraken with professional support for Mac, Windows and Linux. This GIT client was presented in the previous document, and is highly recommended since it adds a GitLab integration to manage different elements. If your workspace doesn’t display the egit interface, click on right button then click “Show in†and choose “Git Repositories†as seen in :numref:`fig22`: .. _fig22: .. figure:: images/3CreatingAdministrating/Picture21.png EGit display menu The EGit menu can be usually found at the bottom left of the Eclipse window: .. figure:: images/3CreatingAdministrating/Picture22.png EGit Interface To download the repository, simply select “Clone a Git repositoryâ€. The following menu will appear asking for an URI. This URI can be found in the GitLab main project interface preceded by the SSH tag (:numref:`fig13`). Be sure that the cloned repository is the fork: .. figure:: images/3CreatingAdministrating/Picture23.png EGit clone menu .. warning:: In the figure 24, the path was changed to match the project name, in this case: FORK-AP242 EGit will complete the **Host**, **Repository path**, **User** and **Passwords** fields. The result should be the same than :numref:`fig22`. You must however precise the communication protocol: SSH. A message indicating that the host authenticity can’t be established will appear. You should indicate that you trust the connection: .. figure:: images/3CreatingAdministrating/Picture24.png Host authenticity warning .. note:: If a passphrase was added when the SSH key was created, a new popup will appear asking you to indicate that value. This is not the git2.boost-lab.net password but the password of the SSH Key you have created in the section 2.2 C .. figure:: images/3CreatingAdministrating/Picture25.png SSH Key passphrase popup The next window will ask you to indicate which branches will need to be cloned. We can see that the branch created on GitLab (in this case AP242) is also available for cloning. Since you are a team leader, it is interesting for you to clone all the branches. .. figure:: images/3CreatingAdministrating/Picture26.png caption .. warning:: Once again, we can see that the repository URL remains the same even if the fork repository name changed. The AP242 branch is the branch created in the section 3.2 B Finally, you will have to select a local directory to where the fork will be cloned. The initial branch that must be selected is the dev branch. By default, the repository in the server will be named “originâ€. This is a GIT convention and is applied by default by every GIT client: .. figure:: images/3CreatingAdministrating/Picture27.png Local directory and initial branch definition Once the project has been cloned, the EGit interface should look like this: .. _fig29: .. figure:: images/3CreatingAdministrating/Picture28.png Imported repository view from EGit As you can see, different kind of branches are created when cloning a repository: the local branches are the physically present branches. In this case, only the dev branch exists. B. Creation of local branches ----------------------------- Since our local repository only has the dev branch, we need to create the AP242 branch (for example) to synchronize the changes from the forked repository locally. To create a new branch, simply right-click on the **Local** section and navigate: **Switch To New Branch...** .. figure:: images/3CreatingAdministrating/Picture29.png New branch menu To make the process easier and faster, the branch name should be the same as the origin branch name. In this case the AP242 name will be used. In the :numref:`fig29`, we indicate to EGit that the newly created branch will be in sync with the origin/AP242 branch. To do so in the **Source** section click on **Select...** and select the origin/AP242 branch: .. figure:: images/3CreatingAdministrating/Picture30.png Branch sync local/fork To download changes from origin (the forked repository), right-click on the repository icon and select **Pull...** .. figure:: images/3CreatingAdministrating/Picture31.png Pull... option The following window will ask from which branch the pull should be done: .. figure:: images/3CreatingAdministrating/Picture32.png Pull menu .. note:: The selected reference will be pulled in the actual branch. Be sure that you are in the correct branch. If not, simply double-click on the branch you want to download information. 4. Working with the upstream repository ======================================= A. Cloning the upstream repository branches ------------------------------------------- Since you are the team leader who has forked the repository, it is your responsibility to keep in sync the forked repository with upstream repository. It will also be your responsibility to create merge requests whenever your project branch is mature enough to be shared in the upstream’s dev branch. To add the upstream repository, right-click the **Remotes** tab and select **Create Remote...**: .. figure:: images/3CreatingAdministrating/Picture33.png Remotes menu The window that will appear will ask you to give a name to the new remote. In this case, and as a GIT good practice process, we will name the remote “upstreamâ€. Be sure to configure the fetch option since we will not push directly to the upstream repository: .. figure:: images/3CreatingAdministrating/Picture34.png Remote creation menu The next step will ask you for an URI. Click on **Change...** and the window like in :numref:`fig18` will appear... Please be sure that the selected URI is the upstream’s URI. This URI can be accessed in the main gitlab page (:numref:`fig15`) by selecting the upstream repository and copying it’s SSH URL: .. figure:: images/3CreatingAdministrating/Picture35.png Additional remote URI definition If the process has been successful, you should now see the upstream branches in the “Remote tracking†branches section: .. figure:: images/3CreatingAdministrating/Picture36.png Remote tracking section after adding the upstream repository B. Creating a merge request in GitLab ------------------------------------- .. note:: This scenario is only applicable if changes have been done in the forked repository. Please check the developper section (nº4) if you want to modify some files to merge them. If the resulting work from the AP242 is mature enough to be merged back into the upstream deb branch, a new merge request will have to be created. To do so, navigate to your GitLab’s fork window and select the **Merge Requests** tab: .. figure:: images/3CreatingAdministrating/Picture37.png Main GitLab's fork menu Simply click on the **New Merge Request** button: .. figure:: images/3CreatingAdministrating/Picture38.png Creation of a new merge request The merge request should be done to integrate the latest changes from a project branch (in this case the AP242) into the “dev†branch from the upstream repository. This can be seen in the following figure, where the AP242 branch from the forked repository will be merged with the dev branch from the upstream repository: .. figure:: images/3CreatingAdministrating/Picture39.png Merge request repository and branch selection After clicking on “Compare branches and continue†we will land on a Merge Request description page. In this page, information related to the merge request will be added. A Description of the changes should be added and detail as much as possible which specific changes have been made. At the bottom of this page, the different commits that are being merged and the modified files are added to have a quick view of the changes. The following figure shows the Merge Request description page: .. figure:: images/3CreatingAdministrating/Picture40.png Merge request description C. Pulling from the upstream repository into a local branch ----------------------------------------------------------- To be able to check if the upstream repository has been updated, right-click on the repository icon and select **Remote -> Fetch…**: .. figure:: images/3CreatingAdministrating/Picture41.png Fetch button Since we want to check if updates have been made in the upstrem repository, select “upstream†in the next window: .. figure:: images/3CreatingAdministrating/Picture42.png Repository selection for fetch If changes have been made in the upstream repository, we want to download them locally. Therefore we want to pull from the upstream repository. To do so checkout to the local dev branch by double clicking on the branch. Then right click on the repository icon and in the menu select **Pull...** .. figure:: images/3CreatingAdministrating/Picture43.png Pull... menu Then select the upstream repository for the Remote field and the dev branch. This way EGit will download the upstream dev changes to our local dev branch. .. figure:: images/3CreatingAdministrating/Picture44.png Pull remote selection Our local dev branch will now contain the latest upstream changes. However the forked repository doesn’t have yet those changes. D. Pushing from the local branch to the fork repository ------------------------------------------------------- We now want to push back our local changes to the fork repository. To do so right click on the local dev branch and select **Push Branch...** .. figure:: images/3CreatingAdministrating/Picture45.png Push branch menu The next window will ask us to where the changes shall be pushed. In this case we want to upload those changes in the forked repository. Therefore, we are going to select as a Remote “origin†and the branch to which we are pushing the changes is the “dev†branch: .. figure:: images/3CreatingAdministrating/Picture46.png Pushing the upstream local changes to fork