manifest: Add a new optional description field

Add a new description optional field to the schema. This field is merely
informative, it has no effect whatsoever in the manifest and/or project
processing.

Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>

src/west/app/project.py

@@ -376,6 +376,7 @@ def do_add_parser(self, parser_adder):
 The following arguments are available:
 
 - name: project name in the manifest
+- description: project description in the manifest
 - url: full remote URL as specified by the manifest
 - path: the relative path to the project from the top level,
   as specified in the manifest where applicable
@@ -464,6 +465,7 @@ def delay(func, project):
 
                 result = args.format.format(
                     name=project.name,
+                    description=project.description or "None",
                     url=project.url or 'N/A',
                     path=path,
                     abspath=apath,

src/west/manifest-schema.yml

@@ -82,6 +82,10 @@ mapping:
           name:
             required: true
             type: str
+          # Project description. Has no effect.
+          description:
+            required: false
+            type: str
           # Name of the project's remote. May not be combined with "url".
           remote:
             required: false

src/west/manifest.py

@@ -53,7 +53,7 @@
 #: v1.0.x, so that users can say "I want schema version 1" instead of
 #: having to keep using '0.13', which was the previous version this
 #: changed.)
-SCHEMA_VERSION = '1.0'
+SCHEMA_VERSION = '1.2'
 # MAINTAINERS:
 #
 # - Make sure to update _VALID_SCHEMA_VERS if you change this.
@@ -195,7 +195,7 @@ class _defaults(NamedTuple):
 _EARLIEST_VER_STR = '0.6.99'  # we introduced the version feature after 0.6
 _VALID_SCHEMA_VERS = [
     _EARLIEST_VER_STR,
-    '0.7', '0.8', '0.9', '0.10', '0.12', '0.13',
+    '0.7', '0.8', '0.9', '0.10', '0.12', '0.13', '1.0',
     SCHEMA_VERSION
 ]
 
@@ -734,6 +734,7 @@ class Project:
     Attributes:
 
     - ``name``: project's unique name
+    - ``description``: project's description
     - ``url``: project fetch URL
     - ``revision``: revision to fetch from ``url`` when the
       project is updated
@@ -777,6 +778,7 @@ def __str__(self):
         return f'<Project {self.name} ({path_repr}) at {self.revision}>'
 
     def __init__(self, name: str, url: str,
+                 description: Optional[str] = None,
                  revision: Optional[str] = None,
                  path: Optional[PathType] = None,
                  submodules: SubmodulesType = False,
@@ -792,6 +794,7 @@ def __init__(self, name: str, url: str,
         (``abspath`` and ``posixpath``) will also be ``None``.
 
         :param name: project's ``name:`` attribute in the manifest
+        :param description: project's description or None
         :param url: fetch URL
         :param revision: fetch revision
         :param path: path (relative to topdir), or None for *name*
@@ -808,6 +811,7 @@ def __init__(self, name: str, url: str,
         '''
 
         self.name = name
+        self.description = description
         self.url = url
         self.submodules = submodules
         self.revision = revision or _DEFAULT_REV
@@ -855,6 +859,8 @@ def as_dict(self) -> Dict:
         '''
         ret: Dict = {}
         ret['name'] = self.name
+        if self.description:
+            ret['description'] = self.description
         ret['url'] = self.url
         ret['revision'] = self.revision
         if self.path != self.name:
@@ -1125,6 +1131,7 @@ def __init__(self, path: Optional[PathType] = None,
         self.name: str = 'manifest'
 
         # Pretending that this is a Project, even though it's not (#327)
+        self.description: str = ''
         self.url: str = ''
         self.submodules = False
         self.revision: str = 'HEAD'
@@ -2351,7 +2358,9 @@ def _load_project(self, pd: Dict, url_bases: Dict[str, str],
 
         userdata = pd.get('userdata')
 
-        ret = Project(name, url, pd.get('revision', defaults.revision), path,
+        ret = Project(name, url, description=pd.get('description'),
+                      revision=pd.get('revision', defaults.revision),
+                      path=path,
                       submodules=self._load_submodules(pd.get('submodules'),
                                                        f'project {name}'),
                       clone_depth=pd.get('clone-depth'),

tests/test_manifest.py

@@ -569,6 +569,35 @@ def test_project_sha(tmpdir):
                       topdir=tmpdir.parent)
     assert project.sha(project.revision) == expected_sha
 
+def test_project_description(tmpdir):
+    m = M('''\
+    defaults:
+      remote: r
+    remotes:
+      - name: r
+        url-base: base
+    projects:
+    - name: foo
+    - name: bar
+      description: bar-description
+    - name: baz
+      description: |
+        This is a long multi-line description
+        for project baz.
+    ''')
+    foo, bar, baz = m.get_projects(['foo', 'bar', 'baz'])
+
+    assert foo.description is None
+    assert bar.description == 'bar-description'
+    desc = 'This is a long multi-line description\n' \
+           'for project baz.\n'
+
+    assert baz.description == desc
+    assert 'description' not in foo.as_dict()
+    assert 'description' in bar.as_dict()
+    assert 'bar-description' == bar.as_dict()['description']
+
+
 def test_project_userdata(tmpdir):
     m = M('''\
     defaults: