File: README.rst

package info (click to toggle)
bst-external 0.18.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 540 kB
  • sloc: python: 2,767; makefile: 57
file content (98 lines) | stat: -rw-r--r-- 3,295 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
BuildStream Plugins
*******************

A collection of plugins for the BuildStream project that are too
specific or prone to change for inclusion in the main repository.

How to use this repo
====================

At the moment, this repo is a sort of incubation repo; it contains things
which explicitly don't yet have strong API guarantees.

Therefore, for the time being we recommend use bst-external as a submodule
for your buildstream projects.

Using the plugins locally within a project
------------------------------------------
To use the bst-external plugins locally within a
`BuildStream <https://gitlab.com/BuildStream/buildstream>`_
project, you will first need to clone the repo to a location **within your
project**::

    git clone https://gitlab.com/BuildStream/bst-external.git

The plugins must be declared in *project.conf*. To do this, please refer
to BuildStream's
`Local plugins documentation <https://buildstream.gitlab.io/buildstream/format_project.html#local-plugins>`_.

Using the plugins as a Python package
-------------------------------------
To use the bst-external plugins as a Python package within a
`BuildStream <https://gitlab.com/BuildStream/buildstream>`_
project, you will first need to install bst-external via pip::

    git clone https://gitlab.com/BuildStream/bst-external.git
    cd bst-external
    pip install --user -e .

To ensure it's installed, try: ``pip show BuildStream-external``, this should
show information about the package.

.. note::
   The -e option ensures that changes made to the git repository are reflected
   in the Python package's behaviour.

Then, the plugins must be declared in the *project.conf*. The implementation of
this is explained in BuildStream's
`Pip plugins documentation <https://buildstream.gitlab.io/buildstream/format_project.html#pip-plugins>`_

Pre-review checklist
====================

Before submitting for review, please check the following:

1. Any new plugins have:
   1.1 Added have a copyright statement attached.
   1.2 An entry point defined in setup.py.
   1.3 Been added to the list in ``doc/source/index.rst``

2. It can be tested. Ideally, with automated tests. At minimum, instructions
   on how the maintainer can test it for themselves.

3. Any non-trivial change that is visible to the user should have a note
   in NEWS describing the change.

   Typical changes that do not require NEWS entries:

   * Typo fixes
   * Formatting changes
   * Internal Refactoring

   Typical changes that do require NEWS entries:

   * Bug fixes
   * New features

Release Policy
==============

The maintainer will create a new release in response to changes that are
significant to users.
The steps to do this are:

1. Check for changes between releases that do not have a NEWS entry.
   1.1. Add any new plugins to the list in ``doc/source/index.rst``.
   1.2. Check that new plugins have an entrypoint in setup.py
2. Create a new release number in NEWS.
3. Update the version in setup.py
4. Update the variables ``version`` and ``release`` in ``doc/source/conf.py``
5. Create and push an annotated tag for this version, containing all the
   items from the latest NEWS entry.


Significant changes include:

* Important bugfixes
* Non-backward-compatible changes
* Specifically-requested changes.