10 Covenants - Revision history

Admin: /* Flags */

2018-11-13T23:00:19Z

Flags

← Older revision		Revision as of 23:00, 13 November 2018
Line 140:		Line 140:
	* 2.0 - change default to true, handle new behavior		* 2.0 - change default to true, handle new behavior
	* 3.0 - remove flag, handle new behavior		* 3.0 - remove flag, handle new behavior



			==Summary==

			Evolve Cautiously

			* Avoid Bad Features
			* Minimize Features
			* Keep Features Narrow
			* Mark Experimental Features “Provisional”
			* Delete Features Gently

			Record History Rigorously

			* Maintain a Changelog
			* Choose a Version Scheme
			* Write an Upgrade Guide

			Change Slowly and Loudly

			* Add Parameters Compatibly
			* Change Behavior Gradually

Admin: /* Flags */

2018-11-13T22:59:30Z

Flags

← Older revision		Revision as of 22:59, 13 November 2018
Line 146:		Line 146:

	[[Category:10 Best]]		[[Category:10 Best]]
	~~[[Category:Lists]]~~
	[[Category:Python]]		[[Category:Python]]

Admin: /* Tenth Covenant: Change Behavior Gradually */

2018-11-13T22:59:12Z

Tenth Covenant: Change Behavior Gradually

← Older revision		Revision as of 22:59, 13 November 2018
Line 140:		Line 140:
	* 2.0 - change default to true, handle new behavior		* 2.0 - change default to true, handle new behavior
	* 3.0 - remove flag, handle new behavior		* 3.0 - remove flag, handle new behavior



			==Flags==

			[[Category:10 Best]]
			[[Category:Lists]]
			[[Category:Python]]

Admin: /* Ninth Covenant: Add Parameters Compatibly */

2018-11-13T22:58:50Z

Ninth Covenant: Add Parameters Compatibly

← Older revision		Revision as of 22:58, 13 November 2018
Line 126:		Line 126:
	move('north', extra_sinuous=True)		move('north', extra_sinuous=True)
	</pre>		</pre>

			==Tenth Covenant: Change Behavior Gradually==

			Here are the steps:

			* Add a flag to opt in to the new behavior, default False, warn if it’s False
			* Change default to True, deprecate flag entirely
			* Remove the flag

			If you follow semantic versioning, the versions might be like so:
			* 1.0 - no flag, expect old behavior
			* 1.1 - add flag, default false
			* 2.0 - change default to true, handle new behavior
			* 3.0 - remove flag, handle new behavior

Admin: /* Ninth Covenant: Add Parameters Compatibly */

2018-11-13T22:56:56Z

Ninth Covenant: Add Parameters Compatibly

← Older revision		Revision as of 22:56, 13 November 2018
Line 118:		Line 118:
	# Error! Can't use positional args, keyword args required.		# Error! Can't use positional args, keyword args required.
	move('north', 'slither', False, True)		move('north', 'slither', False, True)
			</pre>

			With the star in place, this is the only syntax allowed:

			<pre>
			# A user's application.
			move('north', extra_sinuous=True)
	</pre>		</pre>

Admin: /* Ninth Covenant: Add Parameters Compatibly */

2018-11-13T22:56:29Z

Ninth Covenant: Add Parameters Compatibly

← Older revision		Revision as of 22:56, 13 November 2018
Line 101:		Line 101:

	Zen of Python: "Errors should never pass silently."		Zen of Python: "Errors should never pass silently."

			The best way to protect your users is with Python 3’s star syntax, which requires callers to pass keyword arguments.

			<pre>
			# Your library code.
			# All arguments after "*" must be passed by keyword.
			def move(direction,
			*,
			mode='slither',
			turbo=False,
			extra_sinuous=False,
			hail_lyft=False):
			# ...

			# A user's application, poorly-written.
			# Error! Can't use positional args, keyword args required.
			move('north', 'slither', False, True)
			</pre>

Admin: /* Sixth Covenant: Maintain a Changelog */

2018-11-13T22:55:42Z

Sixth Covenant: Maintain a Changelog

← Older revision		Revision as of 22:55, 13 November 2018
Line 39:		Line 39:

	announce when a feature is added or deprecated or deleted		announce when a feature is added or deprecated or deleted

			==Seventh Covenant: Choose a Version Scheme==

			==Eighth Covenant: Write an Upgrade Guide==

			example:

			<pre>
			Upgrade to 1.1 and test your code with:
			python -Werror::DeprecationWarning

			Now it's safe to upgrade.
			</pre>

			The Twisted project’s Compatibility Policy explains this beautifully:

			“The First One’s Always Free”

			Any application which runs without warnings may be upgraded
			one minor version of Twisted.

			In other words, any application which runs its tests without triggering
			any warnings from Twisted should be able to have its Twisted version
			upgraded at least once with no ill effects except the possible production
			of new warnings.


			==Ninth Covenant: Add Parameters Compatibly==

			add new parameters with default values that preserve the original behavior

			Over time, parameters are the natural history of your function’s evolution.

			Parameters are listed oldest first, each with a default value.

			Library users can pass keyword arguments to opt in to specific new behaviors, and accept the defaults for all others.

			I like a technique like this one that detects whether any user’s code is relying on this parameter:

			<pre>
			# Your library code.

			_turbo_default = object()

			def move(direction,
			mode='slither',
			turbo=_turbo_default,
			extra_sinuous=False,
			hail_lyft=False):
			if turbo is not _turbo_default:
			warnings.warn(
			"'turbo' is deprecated",
			DeprecationWarning,
			stacklevel=2)
			else:
			# The old default.
			turbo = False
			</pre>

			But this only raises a warning

			Zen of Python: "Errors should never pass silently."

Admin: /* Sixth Covenant: Maintain a Changelog */

2018-11-13T22:51:59Z

Sixth Covenant: Maintain a Changelog

← Older revision		Revision as of 22:51, 13 November 2018
Line 36:		Line 36:
	==Sixth Covenant: Maintain a Changelog==		==Sixth Covenant: Maintain a Changelog==

	~~Your library must have~~ a ~~change log; its main purpose is to~~ announce when a feature ~~that your users rely on~~ is deprecated or deleted.		keep a changelog

			announce when a feature is added or deprecated or deleted

Admin: /* Fifth Covenant: Delete Features Gently */

2018-11-13T22:51:42Z

Fifth Covenant: Delete Features Gently

← Older revision		Revision as of 22:51, 13 November 2018
Line 33:		Line 33:
	> python3 -Werror::DeprecationWarning script.py		> python3 -Werror::DeprecationWarning script.py
	</pre>		</pre>

			==Sixth Covenant: Maintain a Changelog==

			Your library must have a change log; its main purpose is to announce when a feature that your users rely on is deprecated or deleted.

Admin: /* Fourth Covenant: Mark Experimental Features "Provisional" */

2018-11-13T22:51:11Z

Fourth Covenant: Mark Experimental Features "Provisional"

← Older revision		Revision as of 22:51, 13 November 2018
Line 20:		Line 20:

	Don't get locked into a dumb feature - if you aren't sure you really want to keep it, mark it as experimental/provisional. Next release, keep what works (mark it official) and discard what doesn't.		Don't get locked into a dumb feature - if you aren't sure you really want to keep it, mark it as experimental/provisional. Next release, keep what works (mark it official) and discard what doesn't.

			==Fifth Covenant: Delete Features Gently==

			This is a promise responsible creators make

			Follow a set of steps - add the new method, deprecate the old method (use Python warnings module),
			There’s a few steps involved in deleting a feature gently. Starting with a lizard that walks with its legs, you first add the new method, “slither”. Next, deprecate the old method.

			Modify unittests so that warnings (which will not normally cause tests to fail) will become exceptions (which will cause the tests to fail):

			<pre>
			> python3 -Werror::DeprecationWarning script.py
			</pre>