View source for HiHAT Development

= HiHAT Development Environment on xstg.modelado.org =


Welcome to the development environment for HiHAT. This is a brief tutorial on how to set up a development environment and work with the existing development infrastructure on xstg. There are two HiHAT project repositories (aka "repos"):
 * HiHAT - public repo for community development
 * hihat_int - internal repo for special development

This wiki page provides information for working with the public HiHAT git repo intended for community use.


=== Software Tools ===
The HiHAT development environment uses the following tools for its Continuous Integration Pipeline:
* git - [https://git-scm.com/book/en/v2 Git Book]
* Gerrit - [https://gerrit-review.googlesource.com/Documentation/index.html#_guides Gerrit Documentation]
* Redmine Bug Tracking - [http://www.redmine.org/ Redmine Overview]
* OpenLDAP + LAM - [https://www.ldap-account-manager.org/lamcms/ LDAP Account Manager (LAM)]


=== Pre-Requisites ===
* Git is a broadly used open source distributed version control utility. This page assumes you have a working knowledge of git.
* Gerrit is a git repo management utility which enables code reviews, verification and merging of patches into git repositories. These functions are typically required in a distributed code development project. A brief introduction to the Gerrit Web User Interface is provided later in this document. You can use it to perform code reviews, check your submissions, check your permissions and membership, etc. You will need it before you start with git. 


=== Before You Code, Caveats ===
* Please read the instructions here completely before you get started
* Make sure your xstg account user name and email match what you provide to the commits in your local git tree (configure your git environment correctly)
* Ensure your origin points to the correct repo URL after cloning
  <nowiki> $ git remote -v</nowiki>
* Keep your commit messages short! The total length should be shorter than 80 chars, the subject line shorter than 70 characters. Your commit might succeed but your push to the upstream repo will fail with a "commit message length exceeded" error. [We can configure this to be more flexible going forward].
* Ensure that your git log shows a Change-Id: line (automatically added by /.git/hooks/commit-msg)


=== Quick Start-Up: Cloning and Submitting Patches Upstream ===
# Sync with the xstg team to ensure you have an account in LDAP on xstg.modelado.org
# Login to [https://xstg.modelado.org/gerrit/ XSTG Gerrit] with that account. This is a necessary step to push your credentials to Gerrit before you undertake git operations from your client system.
# Clone the HiHAT git repo on your local system
#:<code> $ git clone https://xstg.modelado.org/gerrit/HiHAT</code>
# In your top level HiHAT git clone directory, move back out the original hooks/ and move the (or use ln -s) the git-hooks dir to .git/      
#:<code> $ mv .git/hooks/ .git/hooks_old</code>
#:<code> $ mv git-hooks .git/hooks</code>
# Make your development changes in your git tree, and commit them to your tree via your usual preferred git operations. e.g.:
#:<code> $ git add .</code>
#:<code> $ git commit .</code>
#:    WARNING! Note the git commit msg length limitation above in the Caveats section!
# Push upstream
#:<code> $ git push origin HEAD:refs/for/master</code>
# Check the Gerrit Web UI to see your patch submission
# Further steps in the code flow can be performed via the Gerrit Web UI (see below). 

=== Project Groups ===
You can check which groups you are in from the Gerrit Web UI -> My -> Groups Dashboard page. 

* '''ldap/hihat-admin''': project admin (same as project owner for now); authority to do all project operations
* '''ldap/hihat-developer''': key developer or maintainer, has authority to approve code submissions (+2 reviews), verify patches (+1 verify  in place of build/test automated verification methods, and most other code-flow activity
* '''ldap/hihat-contributor''': individual contributor who can clone repos, submit patches, and provide +1 level code reviews, etc.



=== Working With Gerrit Web UI ===
Gerrit is a git repo manager providing code review and verification of patches for submission to a git repository. Gerrit stages submitted patches and provides powerful, fine-grained control over all aspects of the git development environment.  The Web User Interface can be confusing at first, hence a few brief tips are provided here. 

Gerrit essentially stages submitted patches for code review, verification and revision. A patchset requires 2 approvals:
* Code Review Approval: It must receive a +2 from a reviewer who is authorized to provide a +2 level approval
* Verification: It must receive a +1 from a member with Verification permissions (group ldap/hihat-developers)

Normally, the verification approval would be obtained automatically from a triggered build/test infrastructure component. However, in the case of the HiHAT project initial phase, we have configured manual verification sign-off from authorized people. At the moment, this group is the ldap/hihat-developers group. A patchset can be submitted into the target branch once both the above approvals have been obtained. 

Patches can be revised and uploaded to the same change-id based on comments and feedback. 

==== Access and Sign-in ====
* Access: https://xstg.modelado.org/gerrit/
* The Sign-in box is on the far top right of the page. On some browsers, you might not see this right away. The Search box can over-extend. 

==== Menus ====
* Top level Gerrit Web UI Menu
** '''All''': Shows you current items in the queue for processing (patches submitted for approval, etc.)
** '''My''': Shows items associated with your account (either open items you submitted or are watching)
** '''Projects''': Lists the visible projects (not in hidden state) being managed by this Gerrit server
** '''People''': group information
** '''Plugins''':
** '''Documentation''': 
* Note that you also need to actually click on a sub-tab, it does not immediately switch the content of the page to the top-level tab
* '''My''' -> '''Groups''' does not always reflect what has been configured in LDAP or on the system. Gerrit does a "lazy load" of data. Before working in git, please make sure you login to the Gerrit Web UI with your account and access projects or changes.

==== Code Review and Verification ====
* You can access the change you want to review from the '''All''' or '''My''' menus  
* Once you click on the change, you will be taken to the dashboard for that change. 
* If you are a recognized group member, you will see the buttons for the functions you are authorized to provide, once they are enabled by required pre-steps and context. 
** For example, individual contributors (ldap/hihat-contrib) will only see '''Reply''' for code reviews. 
** Developers (ldap/hihat-developers) will see a '''Reply''' button, but once there is a +2 Code Review, they will also see a button to '''Verify''' (provide +1 verify approval). 
** Once a change has received Code Review approval as well as Verification Step approval, developers will also see the '''Submit''' button to merge the change into the tree.