Build: implement build.jobs config file key

[humitos]

Allow people to use build.jobs to execute pre/post steps.

build:
  jobs:
    pre_install:
      - echo `date`
      - python path/to/myscript.py
    pre_build:
      - sed -i **/*.rst -e "s|{version}|v3.5.1|g"

See a full example of a working config file: https://github.com/readthedocs/test-builds/blob/build-jobs/.readthedocs.yaml

Decisions made

• build.jobs can't be used without build.os / build.tools. This is done on purpose to avoid maintaining old/deprecated features (config file v1 and v2 with build.image)
• CWD path is the path where the repository was cloned
• none of the "internal jobs" (checkout, install, build, etc) can be overwritten in this initial version. We will need a defined contract (e.g. metadata.yaml) to allow this
• we are not escaping the commands the user wrote in the YAML. They are run as-is without modification
• all user's commands are executed via the default Docker user (e.g. docs)
• users can't execute commands as root
• one, many or all the pre/post jobs can be defined
• all user's commands receive environment variables

Closes #8201
Closes #5989

[humitos]

Blocking this PR because I'm going on vacation next week and it makes sense to help with deployment and QA.

[ericholscher]

This looks like a great start. I'm excited to get this out.

I'd like to see the docs included in this PR, which I think would help explain the use case. Also probably some kind of guide content or similar that shows what is possible here, with a few examples and suggestions.

[ericholscher]

Can we use .get() instead of getattr()? Is it not a dict?

[humitos]

No, it's not a dict. It's a BuildJobs instance. The config itself is an object and each of its attributes are objects 🤷🏼

[stsewd]

all jobs should be already defined by this step, you can omit the getattr step.

[humitos]

@stsewd hrm, but how do you access the field name stored in the variable job?

[stsewd]

ah, job is a variable, then the default from [] could be removed, that way we can also catch errors if we pass a wrong job name.

[stsewd]

You can write this as if self.data.config.using_build_tools:, and all jobs should already be defined by this step, so no need for getattr on the right side of this expression.

[humitos]

Hrm, I'd swear that I wrote a comment about this already. Here is my second attempt 😄

I made the requested changes and answered all the questions you had. I think this PR is ready to be merged after it gets approval. Let me know if there is anything else to be done before merging. I tested it locally with test-builds and it worked. However, I'm sure there may be more use cases to test. If you have one in mind, please create the branch in test-builds so we can test it and track it.

[ericholscher]

@humitos I don't see any docs in this PR. Is the idea here that we'll ship the code without docs to be able to test it? I'd still like to understand a bit more the UX of the proposed code via docs, so perhaps we could make another PR that adds docs but isn't merged in the same release?

[ericholscher]

This looks great to me, and I'm excited to get it out to our users. Next step is trying to tell people that they are supported & promote it's usage!

I'd love to have a KPI here on projects using this feature as a test for future "go to market" of new features. I expect this one will be quickly adopted if we do our jobs right. Can we do this easily in metabase these days?

[humitos]

I'd love to have a KPI here on projects using this feature as a test for future "go to market" of new features. I expect this one will be quickly adopted if we do our jobs right. Can we do this easily in metabase these days?

I've used "contains" over the Build._config text field in Metabase, but it's not super clean. However, we migrated that field to a JSON field now, so we should re-write those questions and use the correct query.

In any case, the short answer is "yes, we can get that data into metabase".

[humitos]

I don't see any docs in this PR. Is the idea here that we'll ship the code without docs to be able to test it? I'd still like to understand a bit more the UX of the proposed code via docs, so perhaps we could make another PR that adds docs but isn't merged in the same release?

Hrm, I thought of deploying this first but I wasn't able to shape it before yesterday. So, if we can write the docs and deploy everything together next week that sounds good to me. Otherwise, we can deploy just the code, for now, to start testing it. I wrote a basic reference documentation following what we have in that page and open a PR in #9056

I'm not sure what could doubt you may have regarding the UX but if you have any specific questions about it, let me know, so we can cover them in a guide. I think it will be good to cover common cases like "Unshallow repository" and "Incorrect version detection" at least.