"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/dev_guide/patching.rst" between
cheetah3-3.2.2.tar.gz and cheetah3-3.2.3.tar.gz

About: Cheetah3 is a template engine and code generation tool for e.g. for Web development or Java, SQL, LaTeX, form email ... (written in Python).

patching.rst  (cheetah3-3.2.2)	:	patching.rst  (cheetah3-3.2.3)
Patching Cheetah		Patching Cheetah
================		================
How to commit changes to CVS or submit patches, how to run the test		How to commit changes to git, or submit patches, or send pull requests,
suite. Describe distutils and how the regression tests work.		how to run the test suite. Describe distutils and how the regression tests
		work.
File Requirements		File Requirements
-----------------		-----------------
The code{Template} class contains not only the Cheetah		The code{Template} class contains not only the Cheetah
infrastructure, but also some convenience methods useful in all		infrastructure, but also some convenience methods useful in all
templates. More methods may be added if it's generally agreed among		templates. More methods may be added if it's generally agreed among
Cheetah developers that the method is sufficiently useful to all		Cheetah developers that the method is sufficiently useful to all
types of templates, or at least to all types of HTML-output		types of templates, or at least to all types of HTML-output
templates. If a method is too long to fit into {Template} -		templates. If a method is too long to fit into {Template} -
skipping to change at line 43		skipping to change at line 44
Testing Changes and Building Regression Tests		Testing Changes and Building Regression Tests
---------------------------------------------		---------------------------------------------
Cheetah ships with a regression test suite. To run the built-in		Cheetah ships with a regression test suite. To run the built-in
tests, execute at the shell prompt:		tests, execute at the shell prompt:
::		::
cheetah test		cheetah test
		To run the test suite with all supported Python versions use ``tox``.
Before checking any changes in, run the tests and verify they all		Before checking any changes in, run the tests and verify they all
pass. That way, users can check out the CVS version of Cheetah at		pass. That way, users can check out the git version of Cheetah at
any time with a fairly high confidence that it will work. If you		any time with a fairly high confidence that it will work. If you
fix a bug or add a feature, please take the time to add a test that		fix a bug or add a feature, please take the time to add a test that
exploits the bug/feature. This will help in the future, to prevent		exploits the bug/feature. This will help in the future, to prevent
somebody else from breaking it again without realizing it. Users		somebody else from breaking it again without realizing it. Users
can also run the test suite to verify all the features work on		can also run the test suite to verify all the features work on
their particular platform and computer.		their particular platform and computer.
The general procedure for modifying Cheetah is as follows:		The general procedure for modifying Cheetah is as follows:
#. Write a simple Python program that exploits the bug/feature		#. Write a simple Python program that exploits the bug/feature
you're working on. You can either write a regression test (see		you're working on. You can either write a regression test (see
below), or a separate program that writes the template output to		below), or a separate program that writes the template output to
one file and put the expected output in another file; then you can		one file and put the expected output in another file; then you can
run {diff} on the two outputs. ({diff} is a utility included on all		run {diff} on the two outputs. ({diff} is a utility included on all
Unix-like systems. It shows the differences between two files line		Unix-like systems. It shows the differences between two files line
by line. A precompiled Windows version is at		by line. A precompiled Windows version is at
http://gnuwin32.sourceforge.net/packages/diffutils.htm, and MacOS		http://gnuwin32.sourceforge.net/packages/diffutils.htm, and MacOS
sources at		sources at
http://perso.wanadoo.fr/gilles.depeyrot/DevTools\_en.html.)		http://perso.wanadoo.fr/gilles.depeyrot/DevTools\_en.html.)
#. Make the change in your Cheetah CVS sandbox or in your installed		#. Make the change in your Cheetah git sandbox or in your installed
version of Cheetah. If you make it in the sandbox, you'll have to		version of Cheetah. If you make it in the sandbox, you'll have to
run {python setup.py install} before testing it. If you make it in		run {python setup.py install} before testing it. If you make it in
the installed version, do { not} run the installer or it will		the installed version, do { not} run the installer or it will
overwrite your changes!		overwrite your changes!
#. Run {cheetah test} to verify you didn't break anything. Then run		#. Run {cheetah test} to verify you didn't break anything. Then run
your little test program.		your little test program.
#. Repeat steps 2-3 until everything is correct.		#. Repeat steps 2-3 until everything is correct.
#. Turn your little program into a regression test as described		#. Turn your little program into a regression test as described
below.		below.
#. When {cheetah test} runs cleanly with your regression test		#. When {cheetah test} runs cleanly with your regression test
included, update the {docs/news.rst} file and check in your changes. If		included, update the {docs/news.rst} file and check in your changes. If
you made the changes in your installed copy of Cheetah, you'll have		you made the changes in your installed copy of Cheetah, you'll have
to copy them back into the CVS sandbox first. If you added any		to copy them back into the git sandbox first. If you added any
files that must be distributed, { be sure to} {cvs add} them before		files that must be distributed, { be sure to} {cvs add} them before
committing. Otherwise Cheetah will run fine on your computer but		committing. Otherwise Cheetah will run fine on your computer but
fail on anybody else's, and the test suite can't check for this.		fail on anybody else's, and the test suite can't check for this.
#. Announce the change on the cheetahtemplate-discuss list and		#. Announce the change on the cheetahtemplate-discuss list and
provide a tutorial if necessary. The documentation maintainer will		provide a tutorial if necessary. The documentation maintainer will
update the Users' Guide and Developers' Guide based on this message		update the Users' Guide and Developers' Guide based on this message
and on the changelog.		and on the changelog.
If you add a directory to Cheetah, you have to mention it in		If you add a directory to Cheetah, you have to mention it in
{setup.py} or it won't be installed.		{setup.py} or it won't be installed.
The tests are in the {Cheetah.Tests} package, aka the {src/Tests/}		The tests are in the {Cheetah.Tests} package, aka the {Cheetah/Tests/}
directory of your CVS sandbox. Most of the tests are in		directory of your git sandbox. Most of the tests are in
{SyntaxAndOutput.py}. You can either run all the tests or choose		{SyntaxAndOutput.py}. You can either run all the tests or choose
which to run:		which to run:
Run all the tests. (Equivalent to {cheetah test}.)		Run all the tests. (Equivalent to {cheetah test}.)
Run only the tests in that module.		Run only the tests in that module.
Run only the tests in the class {CGI} inside the module. The class		Run only the tests in the class {CGI} inside the module. The class
must be a direct or indirect subclass of		must be a direct or indirect subclass of
{unittest\_local\_copy.TestCase}.		{unittest\_local\_copy.TestCase}.
End of changes. 6 change blocks.
7 lines changed or deleted		10 lines changed or added

---