diff options
author | Christoph Reiter <creiter@src.gnome.org> | 2017-12-20 15:59:05 +0100 |
---|---|---|
committer | Christoph Reiter <creiter@src.gnome.org> | 2017-12-20 16:26:10 +0100 |
commit | a109b4c96537e8ba3062a56699f3aefc63c82d6d (patch) | |
tree | e267d2d05a5bf3d577b57599b588f8af13597d03 /docs | |
parent | df77beb730c336e5fdc87f4225af0842edfbe56a (diff) | |
download | pygobject-a109b4c96537e8ba3062a56699f3aefc63c82d6d.tar.gz |
docs: convert NEWS file to reST and link bugs
Looks nicer in the online docs and makes it easier to look
up bugs and link to specific releases.
Rename the custom reST role for bugs from gnomebug to bzbug.
With the upcoming move to gitlab that makes it more clear that those
are referencing bugzilla.
Adjust the "make release-news" target to output something similar
to the new format to make converting to reST easier.
Update the maintainer release todo list to state that the changelog
should be copied from stable branches to master. It would be
nice if the NEWS file in master, which gets exposed on readthedocs,
would contain all the information available.
Diffstat (limited to 'docs')
-rw-r--r-- | docs/Makefile | 2 | ||||
-rw-r--r-- | docs/changelog.rst | 1 | ||||
-rw-r--r-- | docs/conf.py | 2 | ||||
-rw-r--r-- | docs/devguide/override_guidelines.rst | 14 | ||||
-rw-r--r-- | docs/maintguide.rst | 2 |
5 files changed, 11 insertions, 10 deletions
diff --git a/docs/Makefile b/docs/Makefile index 7b132252..91dc99c5 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -6,7 +6,7 @@ all: _build images/%.svg: images/%.dia dia $< --export=$@ --filter=dia-svg -_build: Makefile *.rst devguide/*.rst guide/*.rst conf.py images/*.png $(DIA_SVGS) ../README.rst +_build: Makefile *.rst devguide/*.rst guide/*.rst conf.py images/*.png $(DIA_SVGS) ../README.rst ../NEWS sphinx-build -b html . _build linkcheck: diff --git a/docs/changelog.rst b/docs/changelog.rst index 2c4f6b12..f7f87131 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -7,4 +7,3 @@ versions with even minor version are stable releases (e.g. 3.28.x) For more details see the GIT log: https://git.gnome.org//browse/pygobject/log .. include:: ../NEWS - :code: diff --git a/docs/conf.py b/docs/conf.py index aff0fff9..5e96538f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,7 +44,7 @@ html_theme_options = { } extlinks = { - 'gnomebug': ('https://bugzilla.gnome.org/show_bug.cgi?id=%s', '#'), + 'bzbug': ('https://bugzilla.gnome.org/show_bug.cgi?id=%s', 'bz#'), } suppress_warnings = ["image.nonlocal_uri"] diff --git a/docs/devguide/override_guidelines.rst b/docs/devguide/override_guidelines.rst index 9315a69b..35f3f4b0 100644 --- a/docs/devguide/override_guidelines.rst +++ b/docs/devguide/override_guidelines.rst @@ -11,19 +11,19 @@ is also a good idea to study the `Zen of Python by Tim Peters In general, overrides should be minimized and preference should always be placed on updating the underlying API to be more bindable, adding features to GI to support the requirement, or adding mechanical features to PyGObject -which can apply generically to all overrides (:gnomebug:`721226` and -:gnomebug:`640812`). +which can apply generically to all overrides (:bzbug:`721226` and +:bzbug:`640812`). If a GI feature or more bindable API for a library is in the works, it is a good idea to avoid the temptation to add temporary short term workarounds in overrides. The reason is this can creaste unnecessary conflicts when the -bindable API becomes a reality (:gnomebug:`707280`). +bindable API becomes a reality (:bzbug:`707280`). * Minimize class overrides when possible. *Reason*: Class overrides incur a load time performance penalty because they require the classes GType and all of the Python method bindings to be - created. See :gnomebug:`705810` + created. See :bzbug:`705810` * Prefer monkey patching methods on repository classes over inheritance. @@ -36,13 +36,13 @@ bindable API becomes a reality (:gnomebug:`707280`). * Avoid overriding ``__init__`` *Reason*: Sub-classing the overridden class then becomes challenging and - has the potential to cause bugs (see :gnomebug:`711487` and reasoning + has the potential to cause bugs (see :bzbug:`711487` and reasoning listed in https://wiki.gnome.org/Projects/PyGObject/InitializerDeprecations). * Unbindable functions which take variadic arguments are generally ok to add Python implementations, but keep in mind the prior noted guidelines. A lot of times adding bindable versions of the functions to the underlying library - which take a list is acceptable. For example: :gnomebug:`706119`. Another + which take a list is acceptable. For example: :bzbug:`706119`. Another problem here is if an override is added, then later a bindable version of the API is added which takes a list, there is a good chance we have to live with the override forever which masks a working version implemented by GI. @@ -58,7 +58,7 @@ bindable API becomes a reality (:gnomebug:`707280`). *Reason*: This turns into a documentation discrepancy between the libraries API and the Python version of the API. Default value work should focus on - bug :gnomebug:`558620`, not cherry-picking individual Python functions and + bug :bzbug:`558620`, not cherry-picking individual Python functions and adding defaults. * Avoid implicit side effects to the Python standard library (or anywhere). diff --git a/docs/maintguide.rst b/docs/maintguide.rst index c9cec1b9..3368a6d3 100644 --- a/docs/maintguide.rst +++ b/docs/maintguide.rst @@ -16,6 +16,8 @@ Making a Release #. Upload tarball: ``scp pygobject-3.X.Y.tar.gz user@master.gnome.org:`` #. Install tarball: ``ssh user@master.gnome.org 'ftpadmin install pygobject-3.X.Y.tar.gz'`` +#. In case the release happens on a stable branch copy the NEWS changes to + the master branch Based on https://wiki.gnome.org/MaintainersCorner/Releasing |