TDE Gitea Workspace

From Trinity Desktop Project Wiki
Revision as of 14:23, 16 September 2018 by imported>Michele Calgaro (→‎To contribute code changes)
Jump to navigation Jump to search


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


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
 cd tde
 git submodule init -- scripts
 git submodule update -- scripts
 ./scripts/switch_all_submodules_to_head_and_clean anonymous
 
 # TDE packaging repository
 cd "<TDE folder>"
 git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde-packaging
  • 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
 
 # TDE packaging repository
 cd "$TDE_DIR" && git pull --rebase

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

If you wish, you can clone TDE packaging repository as follow (make sure NOT to be in the <module folder> before you go ahead). 

 git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde-packaging
  • 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

If you have also cloned the packaging folder: 

 cd "<tde-packaging folder>" && git pull --rebase


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.

  • 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

You can easily provide patches and code changes for review by creating pull requests (PR). 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. The only requirement for contributors is to agree with the Developer Certificate of Origin by signing off each commit appropriately. This is to ensure that the contributor has the rights to submit such 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.
  • 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, but it is not absolutely necessary.


TO BE CONTINUED

As a TDE developer

TODO

Retrieved from "https://wiki.trinitydesktop.org/index.php?title=TDE_Gitea_Workspace&oldid=694"