qiboteam / workflows Goto Github PK

Also the job evaluate-label is now repeated three times (even if still in the other org). We should factorize it as well, for maintainability.

E.g.:
https://github.com/qiboteam/qibo/blob/1593c60e042cb44cd0e4eb35fe0c731b717a550b/.github/workflows/publish.yml#L11-L27

It should be: https://qibo.science/workflows/

Workflows inputs allow a description key.

We already describe extensively the parameters in the docs, but a brief, in-place description might still be useful (but, as said brief).

Import them from qibo and the other existing repos:
https://github.com/qiboteam/qibo/tree/master/.github/workflows

They should be as little as possible, i.e. reuse them as much as possible.

If you can, use the same one (per-kind) for all repos (e.g. only one unit testing, only one deploying on PyPI).
But try to limit as well the number of inputs: if they are too different, keep multiple different workflows.

• qibo qiboteam/qibo#763
• qibolab
• qibocal
• qibojit
• qibosoq

Notice qibocal is the only package using Poetry, at present time, so we might have a separate copy for it, but (as said above), better if we can just support both layouts with minimal branching on the same set of workflows.

https://github.com/qiboteam/workflows/pull/23/files#r1090696112

For the time being we just introduced them, so it was not a major concern, but now we start seeing syncing issues between workflows and repos using them.

Problem is that we are still developing them, so it is quite normal that during development you iterate faster, but we should make such that callers never use development versions, but instead "named" ones, such we do not need to update them constantly.

Following the example of actions/checkout and similar actions, we will offer two "lines":

• the tags, fully qualified, e.g. v3.0.2, according to semver
• the branches, e.g. v3, following a family of major releases
  • actions/checkout uses tags also for these, updating them every time something is published. To me, this partially misses the purpose of tags, since you'd like to consider them fixed points in Git history

So, if you want to have an immutable object, just use the fully qualified tag in your workflow, like [email protected].
If instead you'd like to receive non-breaking updates, use the less qualified branch v3.

Unqualified branches like main will be dropped or reserved to development, and they should not be used by callers.
In particular, we won't have a branch named main (nor master, nor trunk) and just use as default branch the latest vX branch.

Let's start from v0, to try a bit the model. We will accept breaking changes in v0 for a transition period, after that we will move to v1 and the first breaking change will directly bump to v2.

Add a README describing the content of this repository, something like

# Workflows

Collection of reusable workflows for the Qibo Gang organization.

## Currently Available

- publish Next.js website to GitHub Pages [`publish-nextjs-to-ghpages`](./.github/workflows/publish-nextjs-to-ghpages.yaml)
- ...

Update docs of all the reusable workflows.

This issue is linked to #23.
As @alecandido suggested, we could remove the occurrence of inputs.environmentand replace it with a dedicated pip extra in the original packages, called ci, and then replace these lines:

        pip install .[${{inputs.pip-extras}}]
        pip install .[ci]

It seems that the post load cache venv is forcing all tests in qibo to fail, e.g.:

https://github.com/qiboteam/qibo/actions/runs/8571390230/job/23491514141

We can wait some days and check if github has fixed this issue, otherwise we should consider dropping it.

Sometimes Pylint errors are preventing the whole unit tests to run, possibly hiding some further failures.

While in principle it is fine to have a reasonable code before testing, whenever there are Pylint errors are usually localized to some small portions of the code, and they would not cause the whole unit tests to fail.

I propose to make the two jobs independent, even keeping them inside a single workflow. Moreover, we do not need to run Pylint on all the combinations of matrix on which we run unit tests, it is sufficient to iterate Python versions, while linting errors should not depend on the os/architecture.

https://github.com/qiboteam/qibo/actions/runs/4342641034/jobs/7583730690#step:6:52

Docs are currently broken https://qibogang.github.io/workflows

It seems to me that it would be better to not test on many platforms with poetry install, but rather to generate a wheel on a single one and pip install it, in order to have the same dependency resolution as my users.

python-poetry/poetry#7746 (comment)

For the way it is written, the wheel releasing workflow is essentially a duplicate of the unit tests one, with the addition of building the wheels at the end, and optionally releasing them.
They are also running on the same events.

At this point, it is better to maintain a single workflow, since building the wheels (and not deploying them) never hurts.

We could simplify maintenance a bit.

Just to have a reference to point, and to remind us we should sooner or later take action about this kind of failures:

• in Post Load cached venv

 Error: The template is not valid. qiboteam/workflows/.github/workflows/rules-poetry.yml@main (Line: 52, Col: 16): hashFiles('**/poetry.lock') couldn't finish within 120 seconds.

https://github.com/qiboteam/qibocal/actions/runs/5309540365/jobs/9610320452#step:29:2

Explanation: hashing Poetry lock files is apparently taking too much on Mac machines (most likely because they are slow), and exceeding a GitHub Actions timeout (that's why they are killed).

Since it's happening after tests is not a real problem, but incredibly annoying.

Solutions I see at the moment:

1. stop testing on MacOS
   • if it's working on Linux and Windows, it's unlikely it won't work on MacOS
   • it is taking a lot to acquire a MacOS machine to run, so these tests are always arriving late anyhow
2. stop caching deps on MacOS
   • it's more minimal
   • it increases the workflow complexity

The most relevant issue, pradyunsg/furo#639, has actually been closed by the author yesterday, together with the publication of a new version on PyPI (2023.03.23).

However, as people have suggested in a comment pradyunsg/furo#639 (reply in thread), the problem still persists even with the new version.
I tested myself that the problem is actually still present.

Because of this, we had to deactivate Poetry's modern installer in #46. E.g.

The moment a fixed wheel will be released, we'll be able to restart using the modern installer.

After qiboteam/qibo#816 only Qibolab will be left without Poetry.

We should review the other minor projects, and check if there is anyone still using the pip workflows, and possibly migrate also that.

Otherwise, I would rather support only a single set of tools for Python packaging, and if there are specific needs local workflows are always available (if there will be a massive need to support setuptools again, we will reconsider - but only if and when it will happen).

To face the issue of failing uploads (e.g. qiboteam/qibolab#276 (comment)) Codecov now suggests to always use a Codecov token also for public repos.
https://community.codecov.com/t/upload-issues-unable-to-locate-build-via-github-actions-api/3954

Our workflows should be already using them, when available:

So we should only confirm that we have token set in all repos, to limit upload failures as much as possible.

@Edoardo-Pedicillo there are a few elements that are hard-coded in the new workflow, e.g.
https://github.com/qibogang/workflows/blob/a22b49c1376335b917f49f18d778f3b4263d4605/.github/workflows/deploy-ghpages-latest-stable.yml#L112
where both the base URL, i.e. https://qibogang.github.io/, and the folder, i.e. qibo/, are spelled out.

They should be replaced by inputs (in the case of the base URL, you can use https://qibo.science/ as default).

Looking into Pylint I discover they also ship a script called symilar, to check for copy-pasted code.

I hope this will never detect anything, but since many people are working on these projects I have a preference for more automated tests (and being shipped by Pylint I consider it reliable and maintained, and we would not need any further dep).

Moreover, I'd like to introduce mypy checks as well, even if as a first step I would make failures opt-in.
Type hints are optional, but also incremental, so mypy will try to infer as much as possible, and more we'll use consistent types and type hints (as it is happening with dataclass, that make them mandatory) more useful mypy checks will be.

Both the workflow with latest&stable and the basic Sphinx one are making use of the same Sphinx docs compiling job.

Instead of propagating fixes and upgrades from one the other, we should split the common part to a third workflow, and call that one.

• split the common part
• update workflows documentation

At the moment, there is a fake page for this repo:
https://qibogang.github.io/workflows/
but it is not a bad idea to have an actual one.

We could bootstrap an extremely simple page with Next.js as well. In general, we want to:

• document/describe everything we do
• have a consistent stack (we don't want to learn new tools every time we a new iteration of a common problem)

One alternative is Sphinx, but there is no Python code, and writing ReStructuredText is more of a pain than Markdown.
The other option, and this is an actual one, is to use the native Jekyll running on GitHub, i.e.

• just make a folder docs top-level with md files
• deploy that folder, even without any workflow

Then my actual proposal for this would be:

• make just md files documentation, to describe and document each workflow, and deploy with basic GitHub tools, no workflow needed
  • @Edoardo-Pedicillo in charge to document the goal and usage of the workflows (especially those written by him)
  • we'll give feedback whenever we'll use; in particular @MatteoRobbiati should migrate his workflow on qibogang.github.io to use the one stored here (whenever will be released on main)
• later on, we will define a Next.js layout (further repo) for this simple docs, and possibly only use in the workflow (so not even in Git), such that we can customize this md docs layout but people using it won't have to take care of Next or JS at all (just writing the md files)
  • not urgent, I will later split to a separate issue to the new layout repo
  • it will provide a uniform layout (different from GitHub standard one, closer to Qibo design) for notes on different repos, without any further overhead wrt to writing md
  • we will version the layout with tags, so the workflow downloading it will use the corresponding tag as a parameter, such that the various repo using the layout won't get unexpected upgrade, but they will have to do it explicitly (but just one parameter, the version, for the full layout)
  • since we need some Next expertise, either it will be done by @MatteoRobbiati or by me

We have some simple documentation for the workflows in the docs/ folder. It is missing for this one.