#1655 Added documentation for static contexts
Merged 16 days ago by mikem. Opened 2 months ago by mcurlej.
mcurlej/fm-orchestrator static_context_docs  into  master

@@ -79,6 +79,11 @@ 

  The ``submit_module_build(...)`` then moves the module builds to "init" state and sends a message on

  the configured message bus.

  

+ There is a build option for MBS which enables us to override stream expansion and define contexts

+ directly. For more information see |docs/STATIC_CONTEXTS.rst|_.

+ 

+ .. |docs/STATIC_CONTEXTS.rst| replace:: ``docs/STATIC_CONTEXTS.rst``

+ .. _docs/STATIC_CONTEXTS.rst: STATIC_CONTEXTS.rst

  

  Backend handles module moved to the "init" state

  ------------------------------------------------

@@ -0,0 +1,52 @@ 

+ Static contexts

+ ===============

+ 

+ - the user can specifically set their own context and dependencies when required through

+   ``mbs_options``. ``mbs_options`` is a dict which is part of the ``xmd`` property and

+   is used to configure additional build options for MBS. To make static contexts work,

+   you need to define ``contexts`` dict inside ``mbs_options`` property.

+ - The context definition needs to be defined in the initial modulemd yaml file. ``contexts``

+   build property overrides any dependencies set through the ``dependencies`` property.

+ - `static contexts` and `stream expansion` are mutually exclusive i. e. the streams defined in

+   ``buildrequires`` and ``requires`` of `static context` will not be expanded and need

+   to be precisely defined by the user. (You can not use `stream expansion` notation as ``[]``

+   or ``-f28`` as this will result in an error)

+ - `static contexts` only override ``context`` of a module stream i. e. the one which

+   is the part of the module streams NSVC. ``build context`` is still calculated and preserved

+   in the resulting build in ``mbs`` property in ``xmd`` so the reuse of builds with the

+   same ``build contexts`` takes place.

+ - as per design of the modulemdlib the only types which can be put inside of the ``xmd``

+   property are ``dict`` and ``string``.

+ 

+ 

+ **Example**:

+ 

+ ::

+ 

+     .

+     .

+     .

+     xmd:

+         mbs_options:

+             contexts:

+                 context1:

+                     buildrequires:

+                         module1: stream1

+                         .

+                         .

+                         .

+                         moduleN: streamN

+                     requires:

+                         moduleN: stream1

+                         .

+                         .

+                         .

+                         moduleN: streamN

+                 .

+                 .

+                 .

+                 contextN:

+                     .

+                     .

+                     .

+ 

The markup here doesn't seem to be valid.

There needs to be a blank line after the #. Static contexts item

The Example: is parsing as an unexpected section title. I'd adjust that markup and probably put the whole example in a literal block or similar.

Overall, this added section does not match the rest of the document that it has been added to.

The document itself is about how dependency resolution works within the mbs code. It is written from the perspective of code execution. It's a high level trace-through of what the code does.

The added section is written more as a user how-to. It seems out of place here and derails the logic of the document. Of course, I think we want a user how-to for this, I just don't think think it quite fits here.

This is an important topic, and we may want to expand the docs on it over time. Perhaps it makes sense to create a STATIC_CONTEXTS.rst file that is user-focused like this. Then we could refer it it both here and in the part of HOW_MBS_BUILDS_MODULES.rst that mentions context computation.

Of course, this document should have an addition too. I think it should follow the process-focus of the rest of the document, probably a short note with a reference to the above.

typos and grammar:

  • we don't need the "a" article before mbs_options. Similarly, "The mbs_options" sounds awkward. Probably drop the "The" there.

  • "mutualy" -> "mutually"

  • "preciselly" -> "precisely"

  • "the only type" -> "the only types"

Perhaps pedantic, but...

You have the terms "main context" and "build context" marked up as code, but those strings are not from the code. We have both the build_context and (main) context fields in the module_builds table. If we're going to use code markup here, perhaps it would make sense to refer to them more like this. Or maybe just use non-code markup for emphasis.

Also, this appears to be the only place in the docs where we talk about the two different contexts. It might worth saying a little more about the difference.

rebased onto 2b5f985

22 days ago

@mikem updated, sorry for the delay.

Build 2b5f985 FAILED!
Rebase or make new commits to rebuild.

rebased onto 62c1b16

22 days ago

Build 62c1b16 FAILED!
Rebase or make new commits to rebuild.

@mikem @breilly investigated the build failure and its a java error is this related to my actual change? I am not touching any code and i rebased from master.

@mcurlej I don't believe so. Looks like it is a problem with the CI itself.

  Post stage
  [Pipeline] script
  [Pipeline] {
  [Pipeline] sh
  + curl -k https://c3i-mbs-pr-1655-git62c1b166-855.cloud.paas.psi.redhat.com/vars
    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                   Dload  Upload   Total   Spent    Left  Speed

  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100  3131    0  3131    0     0  97843      0 --:--:-- --:--:-- --:--:--   98k
  [Pipeline] readJSON
  [Pipeline] }
  [Pipeline] // script
  Error when executing always post condition:
  net.sf.json.JSONException: Invalid JSON String
    at net.sf.json.JSONSerializer.toJSON(JSONSerializer.java:143)
    at net.sf.json.JSONSerializer.toJSON(JSONSerializer.java:103)
    at net.sf.json.JSONSerializer.toJSON(JSONSerializer.java:84)
    at org.jenkinsci.plugins.pipeline.utility.steps.json.ReadJSONStepExecution.doRun(ReadJSONStepExecution.java:86)
    at org.jenkinsci.plugins.pipeline.utility.steps.AbstractFileOrTextStepExecution.run(AbstractFileOrTextStepExecution.java:32)
    at org.jenkinsci.plugins.workflow.steps.SynchronousNonBlockingStepExecution.lambda$start$0(SynchronousNonBlockingStepExecution.java:47)
    at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515)
    at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
    at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
    at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
    at java.base/java.lang.Thread.run(Thread.java:834)

All the unit tests passed except for the one we have set to skip.

$ grep 'tests/.*%' jenkins.log |grep -v PASSED
  [logs:build/mbs-backend-build-855-cc57b8d-1] 2020-10-08T13:39:11.761455000Z tests/test_build/test_build.py::TestBuild::test_submit_build_buildonly SKIPPED [  3%]

Shouldn't the contexts: section be indented another step in the example?

rebased onto f53f240

16 days ago

Build f53f240 FAILED!
Rebase or make new commits to rebuild.

Commit 36ca6c6 fixes this pull-request

Pull-Request has been merged by mikem

16 days ago