Difference between revisions of "TDE Gitea Workspace"

From Trinity Desktop Project Wiki
Jump to navigation Jump to search
imported>Michele Calgaro
m (rename repositry to workspace)
imported>SlavekB
(→‎Cloning the complete TDE code: Update instructions for cloning the entire repository tree)
(28 intermediate revisions by 2 users not shown)
Line 4: Line 4:
 
='''About Gitea'''=
  
='''About Gitea'''=
   
−
[https://gitea.io/en-us Gitea] is, as described on their official website, a "painless self-hosted Git service".
 +
[https://gitea.io/ Gitea] is, as described on their official website, a "painless self-hosted Git service".
   
 
It provides a free, self-hosted and easy way to maintain and share GIT repositories and facilitate collaboration among several contributors, providing a workflow similar to that offerred by other websites such as GitHub, GitLab and many others.
  
It provides a free, self-hosted and easy way to maintain and share GIT repositories and facilitate collaboration among several contributors, providing a workflow similar to that offerred by other websites such as GitHub, GitLab and many others.
Line 12: Line 12:
   
 
The official TDE source code is stored on the main Trinity Desktop servers and is available both through [[Project_GIT_Information|Git]] or [https://git.trinitydesktop.org/cgit web interface]. External [http://mirror.git.trinitydesktop.org/cgit mirrors] also provide access to the source code.<br>
  
The official TDE source code is stored on the main Trinity Desktop servers and is available both through [[Project_GIT_Information|Git]] or [https://git.trinitydesktop.org/cgit web interface]. External [http://mirror.git.trinitydesktop.org/cgit mirrors] also provide access to the source code.<br>
−
None of these methods allows users to easily propose software changes or bug fixes, having to email patches to one of the TDE core developers or uploading code to the [https://bugs.trinitydesktop.org TDE bugszilla] in order to do that.
 +
None of these methods allows users to easily propose software changes or bug fixes, having to email patches to one of the TDE core developers or uploading code to the [https://bugs.trinitydesktop.org TDE bugzilla] in order to do that.
   
   
−
The [https://mirror.git.trinitydesktop.org/gitea TDE Gitea Workspace] has been set up with the aim of providing:
 +
The [https://mirror.git.trinitydesktop.org/gitea TDE Gitea Workspace (TGW)] is a copy of the official source code repositories that is synchronized with the main server on a hourly basis. It offers wider bandwidth and a collaboration workflow that helps achieving the aim of providing:
 
* fast access to the source code, both through Git or web interface
  
* fast access to the source code, both through Git or web interface
 
* an easy tool for users and external developers to propose code changes and improvements
  
* an easy tool for users and external developers to propose code changes and improvements
Line 22: Line 22:
   
   
−
TDE Gitea Workspace serves the needs of the following groups:
 +
TGW serves the needs of the following groups:
−
* people who want to have fast read-only access to the TDE source code
 +
* people who want to have fast anonymous read-only access to the TDE source code
−
* users who intend to contribute a few patches here and there on a non regular basis
 +
* users who intend to report bugs and propose ideas for ehnancement
−
* contributors who intend to submit code changes on a regular basis with the aim of becoming long term TDE developers
 +
* contributors who intend to submit code changes for inclusion into TDE official source code
  +
* developers who want to cooperate on some common functionality or bug fix
   
   
  +
[[File:TGW_Repository.png|321px]][[File:TGW_Pulls.png|321px]]
−
=='''TODO'''==
  
  +
<br/><br/>
  +
  +
=='''Internal structure'''==
  +
  +
TGW has been setup as a set of git repositories which constantly mirror the contents of the main TDE git server, with synchronization performed automatically each hour. The bandwidth of the server hosting gitea is bigger than that of the main server, therefore it will serve users in a faster way.<br>
  +
In addition to hosting the TDE source code, each repository offers additional features to help reporting issues, suggest improvements, tracking milestones and contribute code changes in an easy and integrated way.<br>
  +
The main branches of each repository (''master'', ''r14.0.x'', ''v3.5.13-sru'') are protected against inhaverted changes and only the core TDE developers can commit changes to those branches. Nevertheless any registered contributor can freely propose code patches and changes for review and inclusion into the main server using the mechanism of '''pull requests''', which makes collaboration and code sharing extremely easy and fast.
  +
  +
  +
='''Using the TDE Gitea Workspace'''=
  +
  +
=='''<span id="CloneTDECode"></span>To access the TDE source code'''==
  +
You can access TGW in read only mode as an unregistered user. This allows you to clone the TDE source code and keep up to date with the latest commits on a regular basis.<br>
  +
Follow the instructions below to clone the complete set of repositories or just a specific module.
  +
  +
===Cloning the complete TDE code===
  +
  +
* Create a base folder for the TDE source code. Then:
  +
  +
# Main TDE repository
  +
cd "<TDE folder>"
  +
git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde
  +
git clone https://mirror.git.trinitydesktop.org/gitea/TDE/scripts tde/scripts
  +
cd tde
  +
./scripts/switch_all_submodules_to_head_and_clean anonymous
  +
  +
* To keep your local copy up to date, run the following commands on a regular basis.
  +
  +
# Main TDE repository
  +
cd "$TDE_DIR"
  +
./scripts/switch_all_submodules_to_head_and_clean anonymous
  +
  +
===Cloning a specific TDE module===
  +
  +
* First find out the required module cloning address by accessing the module on the [https://mirror.git.trinitydesktop.org/gitea TDE Gitea Workspace]. An https cloning link is provided on the main page of each repository.<br>
  +
*:
  +
*:[[File:Gitea_module_cloning_address.jpeg|800px|Module cloning address example]]<br>
  +
  +
  +
Then:
  +
  +
git clone <module cloning address>
  +
cd "<module folder>"
  +
git submodule init
  +
git submodule update
  +
  +
* To keep your local copy up to date, run the following commands on a regular basis.
  +
  +
cd "<module folder>" && git pull --rebase && git submodule update
  +
  +
  +
=='''To report bugs and suggest enhancements'''==
  +
  +
In order to report issues and suggest improvements, you need to be a registered user. Click on the [https://mirror.git.trinitydesktop.org/gitea/user/sign_up Register] button on the top right corner of the main webpage to access the registration page. Once you have successfully created an account and logged in, you can start reporting bugs.
  +
  +
Please note that as a simple user, you will '''not''' be allowed to create your own repositories. Only contributors and TDE developers have access to such feature.
  +
  +
* Select the appropriate repository from the [https://mirror.git.trinitydesktop.org/gitea/explore/repos Explore] page (1).<br>
  +
*:
  +
*:[[File:TGW issue 1.jpg|800px|TGW issue select repository example]]<br>
  +
  +
  +
* Click on the '''Issues''' tab (2) and then on the '''New Issue''' button (3).<br>
  +
*:
  +
*:[[File:TGW-issue-2.jpg|800px|TGW issue create example]]<br>
  +
  +
  +
* Assign a title (4) and type in a description (5) of the problem or enhancement you are reporting.
  +
* Optionally, you can assign one or more labels (6) to the report, for better categorization.
  +
* '''Do not''' assign any milestone to the issue report. Milestones are set by developers when an issue is closed.
  +
* Finally click the '''Create Issue''' button (7) to finalize your actions and actually file the report.<br>
  +
*:
  +
*:[[File:TGW-issue-3.jpg|800px|TGW issue create example]]<br>
  +
  +
=='''<span id="ContributeCode"></span>To contribute code changes'''==
  +
  +
TGW is based on the '''shared collaboration with branches''' model. There is plenty of information on the internet regarding this, but in brief this is what you need to know:
  +
  +
* Contributors need to be registered and added to the respective "Contributors" group by one of the TGW administrators.
  +
  +
* Avoid forking an existing repository.
  +
  +
* Create your own local branch, work on some changes/features and submit a pull request (PR) to provide patches and code for review. Once a TDE developer has reviewed and approved the PR, the new code will be merged into the main repository and will become part of the official TDE source code.
  +
  +
* Each contributors is required to agree with the [https://developercertificate.org Developer Certificate of Origin (DCO)] by signing off each commit appropriately, using the additional '-s' flag. This is to ensure that the contributor has the rights to submit such code.
  +
  +
* As a contributor, you will also be able to create your own private repositories. This could be useful for example if you intend to work on adding new applications to TDE and you need a working repository for your code.
  +
  +
To contribute code, follow the steps below.
  +
  +
* First of all, you need to be a registered user. Click on the [https://mirror.git.trinitydesktop.org/gitea/user/sign_up Register] button on the top right corner of the main webpage to access the registration page. Once you have successfully created an account and logged in, get in touch with SlavekB or MicheleC on the Trinity [https://www.trinitydesktop.org/mailinglist.php mailing lists] or [https://www.trinitydesktop.org/support.php IRC channel] and ask to be added as a contributor. Once this is confirmed, you will be allowed to submit code patches and create PRs.
  +
  +
* Optionally, you can register your SSH and GPG public keys within TGW. The first allows git to access repositories using ssh instead of https, the second is used by gitea to verify the authenticity of the signature of your commits and display a pad lock near them, as long as the '-S' flag was used when the changes were committed (please note that '-s' (sign-off) and '-S' (sign) have different meanings). To register your keys, follow these steps:
  +
*:
  +
# Click the "Settings" button on the popup menu that appears when you click on the little down arrow near your user avatar at the top right corner of the page.
  +
#:
  +
#:[[File:TGW settings.jpg|250px|TGW settings]]<br><br>
  +
#:
  +
#:
  +
# Click on the "SSH / GPG Keys" tab (1) to display the related page and then use the "Add key" buttons (2)(3) to add the corresponding keys.
  +
#:
  +
#:[[File:TGW-keys.jpg|800px|TGW keys]]<br><br>
  +
#:
  +
  +
* Clone the code of the repository you intend to work on or clone the entire TDE code. See instructions [[#CloneTDECode|here]].
  +
  +
* Create a new branch, which will later be used to generate a pull request in TGW. The name can be anything, but the following guidelines are recommended.
  +
  +
git checkout -b branch_type/descriptive_name
  +
  +
Example of possible branch names are as follow:
  +
  +
- issue/#####/whatever -> related to TGW issue #####
  +
- bug/#####/whatever -> related to bugzilla bug report #####
  +
- feat/whatever -> feature branch, used to propose a new feature, fix, improvement, etc ...
  +
- drop/whatever -> drop branch, used to propose dropping some code or functionality
  +
- other/whatever -> for anything else that does not fit in the previous categories
  +
  +
* Work on your local copy to prepare changes for later submission. Commit as you see fit and when you are ready to share your work, go to the next step. It is highly recommended to test your code prior to create a PR, although this is not strictly mandatory.
  +
*:
  +
*:<span style="color:#ff0000">'''NOTE''': it is very important that you sign-off each of your commits with the '-s' flag, in accordance with the aforementioned [https://developercertificate.org DCO]. Commits that have not been signed-off will not be accepted and will need to be resubmitted after signing-off.</span>
  +
  +
* Upload your changes to TGW. The first time you need to push a new branch as follow:
  +
  +
git push -u origin branch_type/descriptive_name
  +
  +
Then each time you need to share more commits on the same branch, use:
  +
  +
git push origin HEAD
  +
  +
* Create a pull request for other members to review.
  +
# Select the appropriate repository from the [https://mirror.git.trinitydesktop.org/gitea/explore/repos Explore] page (1).<br>
  +
#:
  +
#:[[File:TGW issue 1.jpg|800px|TGW PR select repository example]]<br><br>
  +
#:
  +
#:
  +
# Click on the '''Pull Requests''' tab (2) and then on the '''New Pull Request''' button (3).<br>
  +
#:
  +
#:[[File:TGW-PR-1.jpg|800px|TGW PR create example]]<br><br>
  +
#:
  +
#:
  +
# From the '''pull from''' combobox, select the branch (4) that you had previously created and pushed.
  +
#:
  +
#:[[File:TGW-PR-select-branch.jpg|800px|TGW PR select branch]]<br><br>
  +
#:
  +
#:
  +
# Fill in a title (5) and comments (6) to describe what the PR is for and optionally add '''labels''' (7) for providing better categorization or status. Then click the '''Create Pull Request''' button (8) to finalize the process.<br>
  +
#:
  +
#:[[File:TGW-PR-create2.jpg|800px|TGW PR create]]<br><br>
  +
#:
  +
#:
  +
  +
* At this stage, the PR has been created and shared with the other users and developers, who can provide feedback, work on additional commits, modify the assigned labels and milestones and in general contribute to further improve the PR if required.
  +
  +
* When possible, a core TDE developer will also take a look and if the PR meets the requirements, it will be merged into the main code base. Otherwise feedback will be provided on what is not right, so that you can refine the code for a later review.
  +
  +
=='''As a TDE developer'''==
  +
In addition to being able to contribute code changes, as a core developer you will also have the ability to merge PRs prepared by other contributors. To become a core TDE developer you will first need to be a regular contributor for a while and the quality of your commits should be such that no major rework or corrections are required in most cases. You can then ask to be promoted to full time developer, should you wish to do so.
  +
  +
To contribute code changes or share your work with other developers for discussion, follow the steps described in the [[#ContributeCode|contribute code]] section. To merge a PR created by another contributor, proceed as described below.
  +
  +
* Checkout the PR branch on your local machine.
  +
  +
git fetch
  +
git checkout <PR branch name>
  +
  +
* Review the code proposed by the contributor and provide feedback or ask for more changes if required. You can also add your own changes by pushing additional commits to the same branch.
  +
*:
  +
*:<span style="color:#ff0000">'''NOTE''': make sure each commit of the contributor has been properly signed-off with the '-s' flag, in accordance with the [https://developercertificate.org DCO]. Commits that have not been signed-off cannot be accepted and you need to ask the contributor to sign-off and resubmit the code.</span>
  +
  +
* Once the PR is deemed good to be merged, make sure to rebase it against the latest commit of the main trunk.
  +
  +
git rebase [-S] <main trunk branch>
  +
  +
where -S is used in case you want to sign your commits with a GPG key and 'main trunk branch' is the branch where the PR is meant to be merged into (master, r14.0.x, v3.5.13-sru).
  +
  +
If there was any change, the commit hashes will have been modified and you will need to force-push the new commits to the remote PR branch.
  +
  +
git push -f origin HEAD
  +
  +
* Merge the PR from the TGW website. You can choose to merge the commits as they are ('''Rebase and Merge''') or compress all commits into a single one ('''Squash and Merge''').
  +
*:
  +
*:[[File:TGW-PR-merge1.jpg|650px|TGW PR merge 1]]<br>
  +
  +
* Confirm the operation by clicking the green button.
  +
*:
  +
*:[[File:TGW-PR-merge2.jpg|650px|TGW PR merge 2]]<br>
  +
  +
* Delete the PR branch, unless the PR has been tagged with the '''keep branch''' label.
  +
*:
  +
*:[[File:TGW-PR-merge3.jpg|650px|TGW PR merge 3]]<br>
  +
  +
* Finally adjust labels and milestones if and as required. Labels are usually removed from a PR when this has been closed, while the milestone should indicate the TDE release in which the change will appear.

Revision as of 09:00, 11 August 2019


About Gitea

Gitea is, as described on their official website, a "painless self-hosted Git service".

It provides a free, self-hosted and easy way to maintain and share GIT repositories and facilitate collaboration among several contributors, providing a workflow similar to that offerred by other websites such as GitHub, GitLab and many others.


TDE Gitea Workspace

The official TDE source code is stored on the main Trinity Desktop servers and is available both through Git or web interface. External mirrors also provide access to the source code.
None of these methods allows users to easily propose software changes or bug fixes, having to email patches to one of the TDE core developers or uploading code to the TDE bugzilla in order to do that.


The TDE Gitea Workspace (TGW) is a copy of the official source code repositories that is synchronized with the main server on a hourly basis. It offers wider bandwidth and a collaboration workflow that helps achieving the aim of providing:

  • fast access to the source code, both through Git or web interface
  • an easy tool for users and external developers to propose code changes and improvements
  • a quick way for code sharing and collaboration amongst developers
  • a simple workflow for reviewing, testing and merging code patches


TGW serves the needs of the following groups:

  • people who want to have fast anonymous read-only access to the TDE source code
  • users who intend to report bugs and propose ideas for ehnancement
  • contributors who intend to submit code changes for inclusion into TDE official source code
  • developers who want to cooperate on some common functionality or bug fix


TGW Repository.pngTGW Pulls.png

Internal structure

TGW has been setup as a set of git repositories which constantly mirror the contents of the main TDE git server, with synchronization performed automatically each hour. The bandwidth of the server hosting gitea is bigger than that of the main server, therefore it will serve users in a faster way.
In addition to hosting the TDE source code, each repository offers additional features to help reporting issues, suggest improvements, tracking milestones and contribute code changes in an easy and integrated way.
The main branches of each repository (master, r14.0.x, v3.5.13-sru) are protected against inhaverted changes and only the core TDE developers can commit changes to those branches. Nevertheless any registered contributor can freely propose code patches and changes for review and inclusion into the main server using the mechanism of pull requests, which makes collaboration and code sharing extremely easy and fast.


Using the TDE Gitea Workspace

To access the TDE source code

You can access TGW in read only mode as an unregistered user. This allows you to clone the TDE source code and keep up to date with the latest commits on a regular basis.
Follow the instructions below to clone the complete set of repositories or just a specific module.

Cloning the complete TDE code

  • Create a base folder for the TDE source code. Then:
 # Main TDE repository
 cd "<TDE folder>"
 git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde
 git clone https://mirror.git.trinitydesktop.org/gitea/TDE/scripts tde/scripts
 cd tde
 ./scripts/switch_all_submodules_to_head_and_clean anonymous
  • To keep your local copy up to date, run the following commands on a regular basis.
 # Main TDE repository
 cd "$TDE_DIR"
 ./scripts/switch_all_submodules_to_head_and_clean anonymous

Cloning a specific TDE module

  • First find out the required module cloning address by accessing the module on the TDE Gitea Workspace. An https cloning link is provided on the main page of each repository.
    Module cloning address example


Then: 

 git clone <module cloning address>
 cd "<module folder>"
 git submodule init
 git submodule update
  • To keep your local copy up to date, run the following commands on a regular basis.
 cd "<module folder>" && git pull --rebase && git submodule update


To report bugs and suggest enhancements

In order to report issues and suggest improvements, you need to be a registered user. Click on the Register button on the top right corner of the main webpage to access the registration page. Once you have successfully created an account and logged in, you can start reporting bugs.

Please note that as a simple user, you will not be allowed to create your own repositories. Only contributors and TDE developers have access to such feature.

  • Select the appropriate repository from the Explore page (1).
    TGW issue select repository example


  • Click on the Issues tab (2) and then on the New Issue button (3).
    TGW issue create example


  • Assign a title (4) and type in a description (5) of the problem or enhancement you are reporting.
  • Optionally, you can assign one or more labels (6) to the report, for better categorization.
  • Do not assign any milestone to the issue report. Milestones are set by developers when an issue is closed.
  • Finally click the Create Issue button (7) to finalize your actions and actually file the report.
    TGW issue create example

To contribute code changes

TGW is based on the shared collaboration with branches model. There is plenty of information on the internet regarding this, but in brief this is what you need to know:

  • Contributors need to be registered and added to the respective "Contributors" group by one of the TGW administrators.
  • Avoid forking an existing repository.
  • Create your own local branch, work on some changes/features and submit a pull request (PR) to provide patches and code for review. Once a TDE developer has reviewed and approved the PR, the new code will be merged into the main repository and will become part of the official TDE source code.
  • Each contributors is required to agree with the Developer Certificate of Origin (DCO) by signing off each commit appropriately, using the additional '-s' flag. This is to ensure that the contributor has the rights to submit such code.
  • As a contributor, you will also be able to create your own private repositories. This could be useful for example if you intend to work on adding new applications to TDE and you need a working repository for your code.

To contribute code, follow the steps below.

  • First of all, you need to be a registered user. Click on the Register button on the top right corner of the main webpage to access the registration page. Once you have successfully created an account and logged in, get in touch with SlavekB or MicheleC on the Trinity mailing lists or IRC channel and ask to be added as a contributor. Once this is confirmed, you will be allowed to submit code patches and create PRs.
  • Optionally, you can register your SSH and GPG public keys within TGW. The first allows git to access repositories using ssh instead of https, the second is used by gitea to verify the authenticity of the signature of your commits and display a pad lock near them, as long as the '-S' flag was used when the changes were committed (please note that '-s' (sign-off) and '-S' (sign) have different meanings). To register your keys, follow these steps:
  1. Click the "Settings" button on the popup menu that appears when you click on the little down arrow near your user avatar at the top right corner of the page.
    TGW settings

  2. Click on the "SSH / GPG Keys" tab (1) to display the related page and then use the "Add key" buttons (2)(3) to add the corresponding keys.
    TGW keys

  • Clone the code of the repository you intend to work on or clone the entire TDE code. See instructions here.
  • Create a new branch, which will later be used to generate a pull request in TGW. The name can be anything, but the following guidelines are recommended.
git checkout -b branch_type/descriptive_name

Example of possible branch names are as follow: 

- issue/#####/whatever   ->   related to TGW issue #####
- bug/#####/whatever     ->   related to bugzilla bug report #####
- feat/whatever          ->   feature branch, used to propose a new feature, fix, improvement, etc ...
- drop/whatever          ->   drop branch, used to propose dropping some code or functionality
- other/whatever         ->   for anything else that does not fit in the previous categories
  • Work on your local copy to prepare changes for later submission. Commit as you see fit and when you are ready to share your work, go to the next step. It is highly recommended to test your code prior to create a PR, although this is not strictly mandatory.
    NOTE: it is very important that you sign-off each of your commits with the '-s' flag, in accordance with the aforementioned DCO. Commits that have not been signed-off will not be accepted and will need to be resubmitted after signing-off.
  • Upload your changes to TGW. The first time you need to push a new branch as follow:
git push -u origin branch_type/descriptive_name

Then each time you need to share more commits on the same branch, use: 

git push origin HEAD
  • Create a pull request for other members to review.
  1. Select the appropriate repository from the Explore page (1).
    TGW PR select repository example

  2. Click on the Pull Requests tab (2) and then on the New Pull Request button (3).
    TGW PR create example

  3. From the pull from combobox, select the branch (4) that you had previously created and pushed.
    TGW PR select branch

  4. Fill in a title (5) and comments (6) to describe what the PR is for and optionally add labels (7) for providing better categorization or status. Then click the Create Pull Request button (8) to finalize the process.
    TGW PR create

  • At this stage, the PR has been created and shared with the other users and developers, who can provide feedback, work on additional commits, modify the assigned labels and milestones and in general contribute to further improve the PR if required.
  • When possible, a core TDE developer will also take a look and if the PR meets the requirements, it will be merged into the main code base. Otherwise feedback will be provided on what is not right, so that you can refine the code for a later review.

As a TDE developer

In addition to being able to contribute code changes, as a core developer you will also have the ability to merge PRs prepared by other contributors. To become a core TDE developer you will first need to be a regular contributor for a while and the quality of your commits should be such that no major rework or corrections are required in most cases. You can then ask to be promoted to full time developer, should you wish to do so.

To contribute code changes or share your work with other developers for discussion, follow the steps described in the contribute code section. To merge a PR created by another contributor, proceed as described below.

  • Checkout the PR branch on your local machine.
git fetch
git checkout <PR branch name>
  • Review the code proposed by the contributor and provide feedback or ask for more changes if required. You can also add your own changes by pushing additional commits to the same branch.
    NOTE: make sure each commit of the contributor has been properly signed-off with the '-s' flag, in accordance with the DCO. Commits that have not been signed-off cannot be accepted and you need to ask the contributor to sign-off and resubmit the code.
  • Once the PR is deemed good to be merged, make sure to rebase it against the latest commit of the main trunk.
git rebase [-S] <main trunk branch>

where -S is used in case you want to sign your commits with a GPG key and 'main trunk branch' is the branch where the PR is meant to be merged into (master, r14.0.x, v3.5.13-sru).

If there was any change, the commit hashes will have been modified and you will need to force-push the new commits to the remote PR branch. 

git push -f origin HEAD
  • Merge the PR from the TGW website. You can choose to merge the commits as they are (Rebase and Merge) or compress all commits into a single one (Squash and Merge).
    TGW PR merge 1
  • Confirm the operation by clicking the green button.
    TGW PR merge 2
  • Delete the PR branch, unless the PR has been tagged with the keep branch label.
    TGW PR merge 3
  • Finally adjust labels and milestones if and as required. Labels are usually removed from a PR when this has been closed, while the milestone should indicate the TDE release in which the change will appear.
Retrieved from "https://wiki.trinitydesktop.org/index.php?title=TDE_Gitea_Workspace&oldid=709"