[Notes] [Git][BuildStream/buildstream][master] 6 commits: contributing.rst: end lines with punctuation

[Tristan Van Berkom <gitlab mg gitlab com>]

Title: GitLab

Tristan Van Berkom pushed to branch master at BuildStream / buildstream

Commits:

• d827dfae
  by Angelos Evripiotis at 2018-10-09T09:12:45Z

  contributing.rst: end lines with punctuation
  

• 9590e8ae
  by Angelos Evripiotis at 2018-10-09T09:12:45Z

  contributing.rst: fix whitespace
  
  No tabs, no lines of only horizontal whitespace.
  

• 6d02e269
  by Angelos Evripiotis at 2018-10-09T09:12:45Z

  contributing.rst: fix typo of 'get_count'
  

• 3ed26a47
  by Angelos Evripiotis at 2018-10-09T09:12:45Z

  contributing.rst: de-paren subclass example
  
  It seems easier to read when separated into two sentences.
  

• 5b22d850
  by Angelos Evripiotis at 2018-10-09T09:12:45Z

  contributing.rst: no spaces before '?'
  

• ac0776f8
  by Tristan Van Berkom at 2018-10-09T09:36:33Z

  Merge branch 'aevri/contributing_fixups' into 'master'
  
  Minor fixups to contributing.rst
  
  See merge request BuildStream/buildstream!866

1 changed file:

• CONTRIBUTING.rst

Changes:

CONTRIBUTING.rst

---

...	...	@@ -14,7 +14,7 @@ if no issue already exists.
14	14
15	15	For policies on how to submit an issue and how to use our project labels,
16	16	we recommend that you read the `policies guide
17		-<https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/BuildStream_policies.md>`_
	17	+<https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/BuildStream_policies.md>`_.
18	18
19	19
20	20	.. _contributing_fixing_bugs:
...	...	@@ -404,7 +404,7 @@ on a Python class in BuildStream::
404	404	# Implementation of the "frobbish" abstract method
405	405	# defined by the parent Bar class.
406	406	#
407		- return True
	407	+ return True
408	408
409	409	################################################
410	410	# Public Methods #
...	...	@@ -445,7 +445,7 @@ on a Python class in BuildStream::
445	445	# Returns:
446	446	# (int): The count of this foo
447	447	#
448		- def set_count(self, count):
	448	+ def get_count(self, count):
449	449
450	450	return self._count
451	451
...	...	@@ -459,7 +459,7 @@ on a Python class in BuildStream::
459	459	# Even though these are private implementation
460	460	# details, they still MUST have API documenting
461	461	# comments on them.
462		-
	462	+
463	463	# _do_frobbing()
464	464	#
465	465	# Does the actual frobbing
...	...	@@ -494,10 +494,10 @@ reference on how the PEP-8 defines public and non-public.
494	494
495	495	A private symbol must be denoted by a leading underscore.
496	496
497		-* When a class can have subclasses (for example, the ``Sandbox`` or ``Platform``
	497	+* When a class can have subclasses, then private symbols should be denoted
	498	+ by two leading underscores. For example, the ``Sandbox`` or ``Platform``
498	499	classes which have various implementations, or the ``Element`` and ``Source``
499		- classes which plugins derive from), then private symbols should be denoted
500		- by two leading underscores.
	500	+ classes which plugins derive from.
501	501
502	502	The double leading underscore naming convention invokes Python's name
503	503	mangling algorithm which helps prevent namespace collisions in the case
...	...	@@ -536,7 +536,7 @@ In order to disambiguate between:
536	536
537	537	* Symbols which are publicly accessible details of the ``Element`` class, can
538	538	be accessed by BuildStream internals, but must remain hidden from the
539		- *"Public API Surface"*
	539	+ *"Public API Surface"*.
540	540
541	541	* Symbols which are private to the ``Element`` class, and cannot be accessed
542	542	from outside of the ``Element`` class at all.
...	...	@@ -586,7 +586,7 @@ is found at ``_artifactcache/artifactcache.py``.
586	586
587	587	Imports
588	588	~~~~~~~
589		-Module imports inside BuildStream are done with relative ``.`` notation
	589	+Module imports inside BuildStream are done with relative ``.`` notation:
590	590
591	591	**Good**::
592	592
...	...	@@ -628,12 +628,12 @@ which exposes an instance variable is the only one in control of the value of th
628	628	variable.
629	629
630	630	* If an instance variable is public and must be modified; then it must be
631		- modified using a :ref:`mutator <contributing_accessor_mutator>`
	631	+ modified using a :ref:`mutator <contributing_accessor_mutator>`.
632	632
633	633	* Ideally for better encapsulation, all object state is declared as
634	634	:ref:`private instance variables <contributing_public_and_private>` and can
635	635	only be accessed by external classes via public :ref:`accessors and mutators
636		- <contributing_accessor_mutator>`
	636	+ <contributing_accessor_mutator>`.
637	637
638	638	.. note::
639	639
...	...	@@ -720,10 +720,10 @@ In BuildStream, we use the term *"Abstract Method"*, to refer to
720	720	a method which **can** be overridden by a subclass, whereas it
721	721	is **illegal** to override any other method.
722	722
723		-* Abstract methods are allowed to have default implementations
	723	+* Abstract methods are allowed to have default implementations.
724	724
725	725	* Subclasses are not allowed to redefine the calling signature
726		- of an abstract method, or redefine the API contract in any way
	726	+ of an abstract method, or redefine the API contract in any way.
727	727
728	728	* Subclasses are not allowed to override any other methods.
729	729
...	...	@@ -798,7 +798,7 @@ BstError parameters
798	798	When raising ``BstError`` class exceptions, there are some common properties
799	799	which can be useful to know about:
800	800
801		-* **message:** The brief human readable error, will be formatted on one line in the frontend
	801	+* **message:** The brief human readable error, will be formatted on one line in the frontend.
802	802
803	803	* **detail:** An optional detailed human readable message to accompany the **message** summary
804	804	of the error. This is often used to recommend the user some course of action, or to provide
...	...	@@ -974,9 +974,9 @@ symbols to a minimum, this is important for both
974	974
975	975	When anyone visits a file, there are two levels of comprehension:
976	976
977		-* What do I need to know in order to *use* this object
	977	+* What do I need to know in order to *use* this object.
978	978
979		-* What do I need to know in order to *modify* this object
	979	+* What do I need to know in order to *modify* this object.
980	980
981	981	For the former, we want the reader to understand with as little effort
982	982	as possible, what the public API contract is for a given object and consequently,
...	...	@@ -1001,9 +1001,9 @@ well documented and minimal.
1001	1001
1002	1002	When adding new API to a given object for a new purpose, consider whether
1003	1003	the new API is in any way redundant with other API (should this value now
1004		-go into the constructor, since we use it more than once ? could this
	1004	+go into the constructor, since we use it more than once? could this
1005	1005	value be passed along with another function, and the other function renamed,
1006		-to better suit the new purposes of this module/object ?) and repurpose
	1006	+to better suit the new purposes of this module/object?) and repurpose
1007	1007	the outward facing API of an object as a whole every time.
1008	1008
1009	1009
...	...	@@ -1183,7 +1183,7 @@ The BuildStream documentation style is as follows:
1183	1183	* Cross references should be of the form ``:role:`target```.
1184	1184
1185	1185	* Explicit anchors can be declared as ``.. _anchor_name:`` on a line by itself.
1186		-
	1186	+
1187	1187	* To cross reference arbitrary locations with, for example, the anchor ``anchor_name``,
1188	1188	always provide some explicit text in the link instead of deriving the text from
1189	1189	the target, e.g.: ``:ref:`Link text <anchor_name>```.
...	...	@@ -1266,23 +1266,23 @@ Documentation Examples
1266	1266	The examples section of the documentation contains a series of standalone
1267	1267	examples, here are the criteria for an example addition.
1268	1268
1269		-* The example has a ``${name}``
	1269	+* The example has a ``${name}``.
1270	1270
1271		-* The example has a project users can copy and use
	1271	+* The example has a project users can copy and use.
1272	1272
1273		- * This project is added in the directory ``doc/examples/${name}``
	1273	+ * This project is added in the directory ``doc/examples/${name}``.
1274	1274
1275		-* The example has a documentation component
	1275	+* The example has a documentation component.
1276	1276
1277	1277	* This is added at ``doc/source/examples/${name}.rst``
1278	1278	* A reference to ``examples/${name}`` is added to the toctree in ``doc/source/examples.rst``
1279	1279	* This documentation discusses the project elements declared in the project and may
1280		- provide some BuildStream command examples
1281		- * This documentation links out to the reference manual at every opportunity
	1280	+ provide some BuildStream command examples.
	1281	+ * This documentation links out to the reference manual at every opportunity.
1282	1282
1283		-* The example has a CI test component
	1283	+* The example has a CI test component.
1284	1284
1285		- * This is an integration test added at ``tests/examples/${name}``
	1285	+ * This is an integration test added at ``tests/examples/${name}``.
1286	1286	* This test runs BuildStream in the ways described in the example
1287	1287	and assert that we get the results which we advertize to users in
1288	1288	the said examples.
...	...	@@ -1309,17 +1309,17 @@ The ``.run`` file format is just another YAML dictionary which consists of a
1309	1309
1310	1310	Each *command* is a dictionary, the members of which are listed here:
1311	1311
1312		-* ``directory``: The input file relative project directory
	1312	+* ``directory``: The input file relative project directory.
1313	1313
1314		-* ``output``: The input file relative output html file to generate (optional)
	1314	+* ``output``: The input file relative output html file to generate (optional).
1315	1315
1316	1316	* ``fake-output``: Don't really run the command, just pretend to and pretend
1317	1317	this was the output, an empty string will enable this too.
1318	1318
1319		-* ``command``: The command to run, without the leading ``bst``
	1319	+* ``command``: The command to run, without the leading ``bst``.
1320	1320
1321	1321	* ``shell``: Specifying ``True`` indicates that ``command`` should be run as
1322		- a shell command from the project directory, instead of a bst command (optional)
	1322	+ a shell command from the project directory, instead of a bst command (optional).
1323	1323
1324	1324	When adding a new ``.run`` file, one should normally also commit the new
1325	1325	resulting generated ``.html`` file(s) into the ``doc/source/sessions-stored/``
...	...	@@ -1417,7 +1417,7 @@ a subdirectory beside your test in which to store data.
1417	1417	When creating a test that needs data, use the datafiles extension
1418	1418	to decorate your test case (again, examples exist in the existing
1419	1419	tests for this), documentation on the datafiles extension can
1420		-be found here: https://pypi.python.org/pypi/pytest-datafiles
	1420	+be found here: https://pypi.python.org/pypi/pytest-datafiles.
1421	1421
1422	1422	Tests that run a sandbox should be decorated with::
1423	1423

—
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.