[Notes] [Git][BuildStream/buildstream][Qinusty/526-fail-on-warnings] 2 commits: docs: Add documentation for Configurable Warnings

[Qinusty <gitlab mg gitlab com>]

Title: GitLab

Qinusty pushed to branch Qinusty/526-fail-on-warnings at BuildStream / buildstream

Commits:

• 689fa6c0
  by Josh Smith at 2018-08-10T15:03:23Z

  docs: Add documentation for Configurable Warnings
  
  This includes detailing the use of `fatal-warnings` within project.conf
  
  This also adds a deprecation notice to the fail on overlaps section.
  

• 6c21c5b8
  by Josh Smith at 2018-08-10T15:03:29Z

  tests: Add tests for configurable warnings
  
  This adds multiple tests for custom plugin warnings and core warnings,
  providing checks for both cases which should cause warnings and errors
  when configured as fatal.
  

10 changed files:

• buildstream/plugin.py
• doc/source/format_project.rst
• + tests/frontend/configurable_warnings.py
• + tests/frontend/configuredwarning/elements/corewarn.bst
• + tests/frontend/configuredwarning/elements/warninga.bst
• + tests/frontend/configuredwarning/elements/warningb.bst
• + tests/frontend/configuredwarning/plugins/corewarn.py
• + tests/frontend/configuredwarning/plugins/warninga.py
• + tests/frontend/configuredwarning/plugins/warningb.py
• + tests/frontend/configuredwarning/project.conf

Changes:

buildstream/plugin.py

---

...	...	@@ -47,6 +47,23 @@ it is mandatory to implement the following abstract methods:
47	47	Once all configuration has been loaded and preflight checks have passed,
48	48	this method is used to inform the core of a plugin's unique configuration.
49	49
	50	+Configurable Warnings
	51	+---------------------
	52	+Warnings raised through calling :func:`Plugin.warn() <buildstream.plugin.Plugin.warn>` can provide an optional
	53	+parameter ``warning_token``, this will raise a :class:`PluginError` if the warning is configured as fatal within
	54	+the project configuration.
	55	+
	56	+Configurable warnings will be prefixed with :func:`Plugin.get_kind() <buildstream.plugin.Plugin.get_kind>`
	57	+within buildstream and must be prefixed as such in project configurations. For more detail on project configuration
	58	+see :ref:`Configurable Warnings <configurable_warnings>`.
	59	+
	60	+It is important to document these warnings in your plugin documentation to allow users to make full use of them
	61	+while configuring their projects.
	62	+
	63	+Example
	64	+~~~~~~~
	65	+If the ``git.py`` plugin uses the warning ``"inconsistent-submodule"`` then it could be referenced in project
	66	+configuration as ``"git:inconsistent-submodule"``.
50	67
51	68	Plugin Structure
52	69	----------------

doc/source/format_project.rst

---

...	...	@@ -126,23 +126,74 @@ following to your ``project.conf``:
126	126	The ``ref-storage`` configuration is available since :ref:`format version 8 <project_format_version>`
127	127
128	128
	129	+.. _configurable_warnings:
	130	+
	131	+Configurable Warnings
	132	+~~~~~~~~~~~~~~~~~~~~~
	133	+Warnings can be configured as fatal using the ``fatal-warnings`` configuration item.
	134	+When a warning is configured as fatal, where a warning would usually be thrown instead an error will be thrown
	135	+causing the build to fail.
	136	+
	137	+When ``fatal-warnings`` is True, all configurable fatal warnings will be set as fatal. Individual warnings
	138	+can also be set by setting ``fatal-warnings`` to a list of warnings.
	139	+
	140	+.. code::
	141	+
	142	+ fatal-warnings:
	143	+ - core:overlaps
	144	+ - core:ref-not-in-track
	145	+ - <plugin>:<warning>
	146	+
	147	+Core Configurable warnings include:
	148	+
	149	+- :ref:`core:overlaps <fail_on_overlaps>`
	150	+- :ref:`core:ref-not-in-track <ref_not_in_track>`
	151	+
	152	+.. note::
	153	+
	154	+ The ``ref-storage`` configuration is available since :ref:`format version 14 <project_format_version>`
	155	+
	156	+.. note::
	157	+
	158	+ Other configurable warnings are plugin specific and should be noted within their individual documentation.
	159	+
	160	+.. _fail_on_overlaps:
	161	+
129	162	Fail on overlaps
130	163	~~~~~~~~~~~~~~~~
131	164	When multiple elements are staged, there's a possibility that different
132	165	elements will try and stage different versions of the same file.
133	166
134		-When ``fail-on-overlap`` is true, if an overlap is detected
135		-that hasn't been allowed by the element's
136		-:ref:`overlap whitelist<public_overlap_whitelist>`,
137		-then an error will be raised and the build will fail.
	167	+.. deprecated:: 1.4
	168	+
138	169
139		-otherwise, a warning will be raised indicating which files had overlaps,
140		-and the order that the elements were overlapped.
	170	+ When ``fail-on-overlap`` is true, if an overlap is detected
	171	+ that hasn't been allowed by the element's
	172	+ :ref:`overlap whitelist<public_overlap_whitelist>`,
	173	+ then an error will be raised and the build will fail.
	174	+
	175	+ Otherwise, a warning will be raised indicating which files had overlaps,
	176	+ and the order that the elements were overlapped.
141	177
142	178	.. code:: yaml
143	179
	180	+ # Deprecated
144	181	fail-on-overlap: true
145	182
	183	+.. note::
	184	+
	185	+ Since deprecation in :ref:`format version 14 <project_format_version>` the recommended
	186	+ solution to this is :ref:`Configurable Warnings <configurable_warnings>`
	187	+
	188	+ When used in combination with ``fatal-warnings``, setting ``fail-on-overlap: False`` can be overriden by ``fatal-warnings``.
	189	+
	190	+
	191	+.. _ref_not_in_track:
	192	+
	193	+Ref not in track
	194	+~~~~~~~~~~~~~~~~
	195	+The configured ref is not valid for the configured track.
	196	+
146	197
147	198	.. _project_source_aliases:
148	199

tests/frontend/configurable_warnings.py

---

	1	+import pytest
	2	+import os
	3	+
	4	+from buildstream.plugin import CoreWarnings
	5	+from buildstream._exceptions import ErrorDomain, LoadErrorReason
	6	+from buildstream import _yaml
	7	+from tests.testutils.runcli import cli
	8	+
	9	+TOP_DIR = os.path.join(
	10	+ os.path.dirname(os.path.realpath(__file__)),
	11	+ "configuredwarning"
	12	+)
	13	+
	14	+
	15	+def get_project(fatal_warnings):
	16	+ return {
	17	+ "name": "test",
	18	+ "element-path": "elements",
	19	+ "plugins": [
	20	+ {
	21	+ "origin": "local",
	22	+ "path": "plugins",
	23	+ "elements": {
	24	+ "warninga": 0,
	25	+ "warningb": 0,
	26	+ "corewarn": 0,
	27	+ }
	28	+ }
	29	+ ],
	30	+ "fatal-warnings": fatal_warnings
	31	+ }
	32	+
	33	+
	34	+def build_project(datafiles, fatal_warnings):
	35	+ project_path = os.path.join(datafiles.dirname, datafiles.basename)
	36	+
	37	+ project = get_project(fatal_warnings)
	38	+
	39	+ _yaml.dump(project, os.path.join(project_path, "project.conf"))
	40	+
	41	+ return project_path
	42	+
	43	+
	44	+@pytest.mark.datafiles(TOP_DIR)
	45	+@pytest.mark.parametrize("element_name, fatal_warnings, expect_fatal, error_domain", [
	46	+ ("corewarn.bst", [CoreWarnings.OVERLAPS], True, ErrorDomain.STREAM),
	47	+ ("warninga.bst", ["warninga:warning-a"], True, ErrorDomain.STREAM),
	48	+ ("warningb.bst", ["warningb:warning-b"], True, ErrorDomain.STREAM),
	49	+ ("corewarn.bst", [], False, None),
	50	+ ("warninga.bst", [], False, None),
	51	+ ("warningb.bst", [], False, None),
	52	+ ("corewarn.bst", "true", True, ErrorDomain.STREAM),
	53	+ ("warninga.bst", "true", True, ErrorDomain.STREAM),
	54	+ ("warningb.bst", "true", True, ErrorDomain.STREAM),
	55	+ ("warninga.bst", [CoreWarnings.OVERLAPS], False, None),
	56	+ ("warningb.bst", [CoreWarnings.OVERLAPS], False, None),
	57	+])
	58	+def test_fatal_warnings(cli, datafiles, element_name,
	59	+ fatal_warnings, expect_fatal, error_domain):
	60	+ project_path = build_project(datafiles, fatal_warnings)
	61	+
	62	+ result = cli.run(project=project_path, args=["build", element_name])
	63	+ if expect_fatal:
	64	+ result.assert_main_error(error_domain, None, "Expected fatal execution")
	65	+ else:
	66	+ result.assert_success("Unexpected fatal execution")

tests/frontend/configuredwarning/elements/corewarn.bst

---

	1	+kind: corewarn
		\ No newline at end of file

tests/frontend/configuredwarning/elements/warninga.bst

---

1

+kind: warninga

tests/frontend/configuredwarning/elements/warningb.bst

---

1

+kind: warningb

tests/frontend/configuredwarning/plugins/corewarn.py

---

	1	+from buildstream import Element
	2	+from buildstream.plugin import CoreWarnings
	3	+
	4	+
	5	+class CoreWarn(Element):
	6	+ def configure(self, node):
	7	+ pass
	8	+
	9	+ def preflight(self):
	10	+ pass
	11	+
	12	+ def get_unique_key(self):
	13	+ pass
	14	+
	15	+ def get_warnings(self):
	16	+ return [] # CoreWarnings should be included regardless of plugins.
	17	+
	18	+ def configure_sandbox(self, sandbox):
	19	+ pass
	20	+
	21	+ def stage(self, sandbox):
	22	+ pass
	23	+
	24	+ def assemble(self, sandbox):
	25	+ self.warn("Testing: CoreWarning produced during assemble",
	26	+ warning_token=CoreWarnings.OVERLAPS)
	27	+
	28	+
	29	+def setup():
	30	+ return CoreWarn

tests/frontend/configuredwarning/plugins/warninga.py

---

	1	+from buildstream import Element
	2	+
	3	+WARNING_A = "warning-a"
	4	+
	5	+
	6	+class WarningA(Element):
	7	+ def configure(self, node):
	8	+ pass
	9	+
	10	+ def preflight(self):
	11	+ pass
	12	+
	13	+ def get_unique_key(self):
	14	+ pass
	15	+
	16	+ def configure_sandbox(self, sandbox):
	17	+ pass
	18	+
	19	+ def stage(self, sandbox):
	20	+ pass
	21	+
	22	+ def assemble(self, sandbox):
	23	+ self.warn("Testing: warning-a produced during assemble", warning_token=WARNING_A)
	24	+
	25	+
	26	+def setup():
	27	+ return WarningA

tests/frontend/configuredwarning/plugins/warningb.py

---

	1	+from buildstream import Element
	2	+
	3	+WARNING_B = "warning-b"
	4	+
	5	+
	6	+class WarningB(Element):
	7	+ def configure(self, node):
	8	+ pass
	9	+
	10	+ def preflight(self):
	11	+ pass
	12	+
	13	+ def get_unique_key(self):
	14	+ pass
	15	+
	16	+ def configure_sandbox(self, sandbox):
	17	+ pass
	18	+
	19	+ def stage(self, sandbox):
	20	+ pass
	21	+
	22	+ def assemble(self, sandbox):
	23	+ self.warn("Testing: warning-b produced during assemble", warning_token=WARNING_B)
	24	+
	25	+
	26	+def setup():
	27	+ return WarningB

tests/frontend/configuredwarning/project.conf

---

	1	+name: test
	2	+element-path: elements
	3	+plugins:
	4	+- origin: local
	5	+ path: element_plugins
	6	+ elements:
	7	+ warninga: 0
	8	+ warningb: 0

—
View it on GitLab.
You're receiving this email because of your account on gitlab.com. If you'd like to receive fewer emails, you can adjust your notification settings.