Merge branch '2026.1' into 'develop'

- **Tag Pipeline**: triggered by the creation of a new official tag (by default starting with `v*`).

:::{note}

From Hog2021.2, new commits into an already opened _non-Draft_ merge request, will interrupt the running pipeline, before starting a new one, unless the pipeline is already at the *Collect* stage.

New commits into an already opened _non-Draft_ merge request, will interrupt the running pipeline, before starting a new one, unless the pipeline is already at the *Collect* stage.

:::

### Merge/Pull Request Pipeline

The *Merge/Pull Request* pipeline simulates, synthesises and implements the chosen HDL projects. If specified, it stores the resulting outputs to an EOS repository and creates the doxygen documentation.

The *Merge/Pull Request* pipeline simulates, synthesises and implements the chosen HDL projects. If specified, it stores the resulting outputs to an external disk space (EOS or local drive) and creates the doxygen documentation.

The stages of the Merge/Pull Request pipeline are the following:

1. *Check*: checks that the source branch is not outdated with respect to the target branch. If it is, the pipeline fails and asks the user to update the source branch.

2. *Generation And Simulation*: the workflow of all the projects is launched.

2. *Generation And Simulation*: the workflow of all the projects is launched. Important files produced during the workflow (binary files, reports, etc.) are saved as artifacts of these jobs.

3. *Collect*: Collects all the artifacts from the previous stages and, if enabled, produces the Doxygen documentation and copies the implementation outputs and the Doxygen documentation to the EOS repository (optionally). Finally a Job is run to check that all the projects meet the timing, if that is not the case the job fails (but not the pipeline).

During the *Generation And Simulation* step, Hog-CI performs the following steps:

- Synthesises the projects. An option to run only up to the synthesis stage is available.

- Implements the projects and creates the bitstreams. An option to disable the bitstream creation is available. During this stage the implementation timing results and project version are also written in the merge request page.

If any of the projects fails timing, Hog stores the full `Projects` folder under the `DebugProjects` name and adds it to the artifacts. This is done to help you debug without having to re run the workflow locally, so these files are not collected in the `collect-artifact` stage.

The *Generation and Simulation* stage is the only one actually running on a private runner. All other stages in the Merge/Pull Request pipelines will instead run on shared-runners, using the Docker container provided by Hog.

Hog also supports a dynamically-generated CI with GitLab CI/CD. For more details, refer to the [Dynamic CI Section](03-GitLab-CI/05-Dynamic-CI.md).

## Hog CI Products

In this paragraph, we describe the output products of the Hog CI pipelines.

### Individual Job products

Each generation and simulation CI job, produces artifacts. The most important artifact is the `bin` folder containing all the binary files prodice to be loaded on the FPGA.

The `bin` floder also contains:

- Synthesis and implementation reports

- The `versions.txt` file contianing all the information about the versions of the built project

- The timing text file, `timing_ok.txt` or `timing_error.txt`

- Optionally IPBus XMLs,  

Other artifact might are added by Hog in some special cases:

- DCPs in case you have enabled the saving of DCPs files with the `HOG_SAVE_DCP` environment variable as explained [here](../03-GitLab-CI/01-setup-CI.md)

- The `DebugProjects` folder is a copy of the whole Projects folder and it's saved only in case the specific project did not meet the timing. As this is done in the individual project's CI job, the folder will only contain the one project and it will not be collected at the collect-articat stage.

### Merge Request Pipeline Products

The Merge Request pipeline generates a `bin` folder, where it stores the output products for each Hog project that has been run over the CI. It can be browsed, by opening the `collect_artifacts` stage of your pipeline and then clicking on `Download` or `Browse` on the right sidebar.

# Authors

Davide Cieri (davide.cieri@cern.ch)

Davide Cieri (Max-Planck-Institute for Physics, Germany)

Francesco Gonnella (francesco.gonnella@cern.ch)

Francesco Gonnella (University of Birmingham, UK)

## Contributors

## Main Contributors

Nordin Aranzabal (nordin.aranzabal@esrf.fr)

Nordin Aranzabal (European Synchrotron Radiation Facility, France)

Nicolo Biesuz (nicolo.vladi.biesuz@cern.ch)

Nicolo Biesuz (INFN Ferrara, Italy)

Rimsky Alejandro Rojas Caballero (rimsky.rojas@cern.ch)

Rimsky Alejandro Rojas Caballero (CERN)

Guillermo Loustau De Linares (guillermo.jose.loustau.de.linares@cern.ch)

Guillermo Loustau De Linares (University of Massachusetts, USA)

Andrew Peck (andrew.peck@cern.ch)

Bryce Natter (NASDAQ, USA)

## Previous Members

## Other Contributors

Nico Giangiacomi (nico.giangiacomi@cern.ch)

 No newline at end of file

Nico Giangiacomi 

Andrew Peck 

    # "use_edit_page_button": True,

    "use_issues_button": True,

    "use_repository_button": True,

    "use_download_button": True

    "use_download_button": True,

    # "expand_sections": ["reference/index"]

    # For testing

    # "home_page_in_toc": True,

    # "single_page": True

    # "extra_footer": "<a href='https://google.com'>Test</a>",

    # "extra_navbar": "<a href='https://google.com'>Test</a>",

    "icon_links": [

        {

            "name": "GitLab",

            "url": "https://gitlab.com/hog-cern/Hog",

            "icon": "https://img.shields.io/gitlab/stars/hog-cern/hog?style=social",

            "type": "url",

        },

        {

            "name": "GitHub",

            "url": "https://github.com/hog-cern/Hog",

            "icon": "https://img.shields.io/github/stars/hog-cern/hog?style=social",

            "type": "url",

        }

    ],

}

# html_title = "My amazing documentation"

If you want to be notified about new Hog releases, please subscribe to our [Newsletter](http://cern.ch/go/nBn8).

:::{tip}

Hog is **completely free** and developed mainly as a pet project by Davide and Francesco. If you use it, please cite [our paper](https://iopscience.iop.org/article/10.1088/1748-0221/16/04/T04006/meta) in your articles and proceedings. Here is the [citation](hog.bib) in BibTeX format.

Hog is **completely free**. It is developed by an international team of researchers from academia and industry ([Author list](05-License/02-Authors)). If you use it, please cite [our paper](https://iopscience.iop.org/article/10.1088/1748-0221/16/04/T04006/meta) in your articles and proceedings. Here is the [citation](hog.bib) in BibTeX format.

:::

### Waste no time thanks to Hog