## Contributing Manual


### Issue reporting and tracking
To report issues and track their progress we use a [JIRA dashboard](https://its.cern.ch/jira/secure/RapidBoard.jspa?rapidView=7215&projectKey=SIGMON&view=detail).

- When a new issue is raised, one can report it by creating a new story on the JIRA board on the `Create` button.
- On step 1. below: The issue moves to the `IN PROGRESS` column as someone starts working on it.
- On step 4. below: When the merge request is open the issue is moved to the `REVIEW` column.
- On step 5. below: When the `DEV` environment has been validated, move the task to `VALIDATION`
- On step 6. below: The issue has been fixed and can be moved to `DONE` column.

Note: issues can move back to their previous steps if needed.

### Fixing an issue

 1. Open a new SWAN session with the configuration
    - Software stack: `NXCals Python3`
    - Platform: `CentOS 7 (gcc7)` - default
    - Environment script: `/eos/project/l/lhcsm/public/contributor.sh`
    - Number of cores: `4`
    - Memory: `16 GB`
    - Spark cluster: `BE NXCALS (NXCals)`
   
   
 2. A new repository `hwc_working` has been created. All the notebooks can be updated from this repository.
    - Update and modify notebooks in order to fix the issue.
    - __IMPORTANT__ -> Before pushing all the notebooks must stay __CLEAN__ !! They should not contain any SWAN execution outputs. 
      To clean a notebook click on the tab `CELL` --> `All Output->Clear`
    - __IMPORTANT__ -> Increment the version number in the `hwc_working/__init__.py` file.  
   

 3. Commit and push your changes to Gitlab:
    - Open the SWAN terminal 
    - Authenticate by running `kinit` and entering your password.
    - Then run the command `source /eos/project/l/lhcsm/public/contributor_push.sh`
    - (Note the working directory `hwc_working` has been deleted, if you want to reload it you can run in the terminal `source /eos/project/l/lhcsm/public/contributor.sh`)
   

 4. Open a merge request on [Gitlab with your changes to be reviewed](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/merge_requests/new?utf8=%E2%9C%93&merge_request%5Bsource_project_id%5D=90588&merge_request%5Bsource_branch%5D=dev&merge_request%5Btarget_project_id%5D=90588&merge_request%5Btarget_branch%5D=master): 
    - select source branch `dev`
    - select target branch `master`
   

 5. Once the merge request has been reviewed and approved then click on the `Merge` button of the merge request page.
    - The `DEV` [pipeline](https://gitlab.cern.ch/LHCData/lhc-sm-api/-/pipelines) is now triggered. Wait until the pipeline is completed and all steps are green.
    - To load the `DEV` environment you can restart the SWAN configuration with the option Environment script: `/eos/project/l/lhcsm/public/packages_notebooks_dev.sh`
   

 6. When changes are validated, you must __TAG__ the `master` branch with the new version: https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/tags/new
    - The `PRO` [pipeline](https://gitlab.cern.ch/LHCData/lhc-sm-api/-/pipelines) is now triggered. Wait until the pipeline is completed and all steps are green.
    - To load the `PRO` environment you can restart the SWAN configuration with the option Environment script: `/eos/project/l/lhcsm/public/packages_notebooks.sh`