RedHatTraining/pyramid.git

Merge pull request #3387 from mmerickel/src-folder-refactor

Michael Merickel

2018-10-15 81576ee51564c49d5ff3c1c07f214f22a8438231

commit \| author \| age
49f5c4	1	Hacking on Pyramid
CM	2	==================
	3
93b6cd	4	Here are some guidelines for hacking on Pyramid.
49f5c4	5
84b496	6
051e27	7	Using a Development Checkout
CM	8	----------------------------
	9
a767d8	10	You'll have to create a development environment to hack on Pyramid, using a
081699	11	Pyramid checkout. You can either do this by hand, or if you have `tox`
CD	12	installed, you can use it to set up a working development environment.
	13
	14	tox docs: http://tox.readthedocs.org/en/latest/
	15	tox on PyPI: https://pypi.org/project/tox/
	16
	17	Each installation method is described below.
84b496	18
995155	19
CM	20	By Hand
	21	+++++++
	22
93b6cd	23	- While logged into your GitHub account, navigate to the Pyramid repo on
SP	24	GitHub.
	25
	26	https://github.com/Pylons/pyramid
	27
	28	- Fork and clone the Pyramid repository to your GitHub account by clicking
	29	the "Fork" button.
	30
	31	- Clone your fork of Pyramid from your GitHub account to your local computer,
	32	substituting your account username and specifying the destination as
	33	"hack-on-pyramid".
995155	34
84b496	35	$ cd ~
SP	36	$ git clone git@github.com:USERNAME/pyramid.git hack-on-pyramid
	37	$ cd hack-on-pyramid
	38	# Configure remotes such that you can pull changes from the Pyramid
	39	# repository into your local repository.
	40	$ git remote add upstream https://github.com/Pylons/pyramid.git
	41	# fetch and merge changes from upstream into master
	42	$ git fetch upstream
	43	$ git merge upstream/master
995155	44
93b6cd	45	Now your local repo is set up such that you will push changes to your GitHub
SP	46	repo, from which you can submit a pull request.
	47
84b496	48	- Create a virtual environment in which to install Pyramid:
995155	49
84b496	50	$ cd ~/hack-on-pyramid
SP	51	$ python3 -m venv env
995155	52
081699	53	From here on in within these instructions, the `~/hack-on-pyramid/env`
CD	54	virtual environment you created above will be referred to as `$VENV`.
995155	55	To use the instructions in the steps that follow literally, use the
081699	56	`export VENV=~/hack-on-pyramid/env` command.
995155	57
84b496	58	- Install Pyramid from the checkout into the virtual environment, where the
081699	59	current working directory is the `pyramid` checkout directory. We will
84b496	60	install Pyramid in editable (development) mode as well as its testing
SP	61	requirements.
995155	62
84b496	63	$ cd ~/hack-on-pyramid
SP	64	$ $VENV/bin/pip install -e ".[testing,docs]"
995155	65
081699	66	- Optionally create a new Pyramid project using `pcreate`:
995155	67
84b496	68	$ cd $VENV
SP	69	$ bin/pcreate -s starter starter
995155	70
84b496	71	- ...and install the new project into the virtual environment:
995155	72
84b496	73	$ cd $VENV/starter
SP	74	$ $VENV/bin/pip install -e .
995155	75
84b496	76
081699	77	Using `Tox`
CD	78	+++++++++++
995155	79
081699	80	Alternatively, if you already have `tox` installed, there is an easier
995155	81	way to get going.
051e27	82
081699	83	- Create a new directory somewhere and `cd` to it:
051e27	84
84b496	85	$ mkdir ~/hack-on-pyramid
SP	86	$ cd ~/hack-on-pyramid
051e27	87
93b6cd	88	- Check out a read-only copy of the Pyramid source:
051e27	89
84b496	90	$ git clone git://github.com/Pylons/pyramid.git .
051e27	91
e39cc8	92	Alternatively, create a writeable fork on GitHub and clone it.
051e27	93
84b496	94	Since Pyramid is a framework and not an application, it can be convenient to
SP	95	work against a sample application, preferably in its own virtual environment. A
0444ed	96	quick way to achieve this is to use `tox` with a custom configuration file
84b496	97	that is part of the checkout:
00a08a	98
84b496	99	$ tox -c hacking-tox.ini
00a08a	100
081699	101	This will create a python-2.7 based virtual environment named `env27`
CD	102	(Pyramid's `.gitconfig` ignores all top-level folders that start with `env`
84b496	103	specifically in our use case), and inside that a simple pyramid application
081699	104	named `hacking` that you can then fire up like so:
00a08a	105
84b496	106	$ cd env27/hacking
SP	107	$ ../bin/pip install -e ".[testing,docs]"
	108	$ ../bin/pserve development.ini
	109
051e27	110
49f5c4	111	Adding Features
CM	112	---------------
	113
	114	In order to add a feature to Pyramid:
4f25f4	115
84b496	116	- The feature must be documented in both the API and narrative documentation
081699	117	(in `docs/`).
4f25f4	118
c8a5e0	119	- The feature must work fully on the following CPython versions: 2.7, 3.4, 3.5,
482075	120	3.6, and 3.7 on both UNIX and Windows.
a3ff61	121
a5c810	122	- The feature must work on the latest version of PyPy.
4f25f4	123
84b496	124	- The feature must not depend on any particular persistence layer (filesystem,
SP	125	SQL, etc).
4f25f4	126
84b496	127	- The feature must not add unnecessary dependencies (where "unnecessary" is of
SP	128	course subjective, but new dependencies should be discussed).
4f25f4	129
84b496	130	The above requirements are relaxed for scaffolding dependencies. If a scaffold
SP	131	has an install-time dependency on something that doesn't work on a particular
	132	platform, that caveat should be spelled out clearly in its documentation
081699	133	(within its `docs/` directory).
4f25f4	134
49f5c4	135
CM	136	Coding Style
	137	------------
	138
84b496	139	- PEP8 compliance. Whitespace rules are relaxed: not necessary to put two
SP	140	newlines between classes. But 79-column lines, in particular, are mandatory.
19d341	141	See https://pylonsproject.org/community-coding-style-standards.html for more
13b187	142	information.
49f5c4	143
cdcea9	144	- Please do not remove trailing whitespace. Configure your editor to reduce
8a3872	145	diff noise. See https://github.com/Pylons/pyramid/issues/788 for more.
cdcea9	146
84b496	147
a3ff61	148	Running Tests
8edd76	149	-------------
a3ff61	150
84b496	151	- To run all tests for Pyramid on a single Python version from your development
SP	152	virtual environment (See Using a Development Checkout above), run
081699	153	`nosetests`:
50f23d	154
84b496	155	$ $VENV/bin/nosetests
SP	156
081699	157	- To run individual tests (i.e., during development), you can use `nosetests`
8edd76	158	syntax as follows:
SP	159
	160	# run a single test
	161	$ $VENV/bin/nosetests pyramid.tests.test_module:ClassName.test_mytestname
	162
	163	# run all tests in a class
	164	$ $VENV/bin/nosetests pyramid.tests.test_module:ClassName
	165
081699	166	Optionally you can install a nose plugin, `nose-selecttests`
CD	167	( https://pypi.org/project/nose-selecttests/ ), and use a regular
	168	expression with the `-t` parameter to run tests.
8edd76	169
SP	170	# run a single test
	171	$ $VENV/bin/nosetests -t test_mytestname
a3ff61	172
081699	173	- The `tox.ini` uses `nose` and `coverage`. As such `tox` may be used
84b496	174	to run groups of tests or only a specific version of Python. For example, the
SP	175	following command will run tests on Python 2.7 only without coverage:
	176
	177	$ tox -e py27
	178
	179	This command will run tests on the latest versions of Python 2 and 3 with
	180	coverage totaled for both versions.
	181
	182	$ tox -e py2-cover,py3-cover,coverage
	183
0444ed	184	- To run the full set of Pyramid tests on all platforms, install `tox` into a
6447d5	185	system Python. The `tox` console script will be installed into the scripts
CD	186	location for that Python. While `cd`'ed to the Pyramid checkout root
	187	directory (it contains `tox.ini`), invoke the `tox` console script. This
	188	will read the `tox.ini` file and execute the tests on multiple Python
	189	versions and platforms. While it runs, it creates a virtual environment
	190	for each version/platform combination. For example:
a3ff61	191
84b496	192	$ sudo /usr/bin/pip install tox
SP	193	$ cd ~/hack-on-pyramid/
	194	$ /usr/bin/tox
a3ff61	195
081699	196	- The tests can also be run using `pytest` ( http://pytest.org/ ). This is
84b496	197	intended as a convenience for people who are more used to or fond of
081699	198	`pytest`. Run the tests like so:
7a2df2	199
84b496	200	$ $VENV/bin/pip install pytest
8fcf0f	201	$ $VENV/bin/pytest --strict pyramid/
84b496	202
8fcf0f	203	To run individual tests (i.e., during development), see "pytest usage -
84b496	204	Specifying tests / selecting tests":
SP	205	http://pytest.org/latest/usage.html#specifying-tests-selecting-tests
7a2df2	206
109b2a	207	- Functional tests related to the "scaffolds" (starter, zodb, alchemy) which
84b496	208	create a virtual environment, install the scaffold package and its
SP	209	dependencies, start a server, and hit a URL on the server, can be run like
	210	so:
109b2a	211
eadaee	212	$ tox -e{py27,py34,py35,py36,py37,pypy}-scaffolds
84b496	213
109b2a	214
49f5c4	215	Test Coverage
CM	216	-------------
	217
aa1c9b	218	- The codebase must have 100% test statement coverage after each commit. You
eadaee	219	can test coverage via `tox -epy2-cover,py3-cover,coverage`.
84b496	220
49f5c4	221
c7fcdf	222	Documentation Coverage and Building HTML Documentation
CM	223	------------------------------------------------------
49f5c4	224
c7fcdf	225	If you fix a bug, and the bug requires an API or behavior modification, all
93b6cd	226	documentation in this package which references that API or behavior must be
SP	227	changed to reflect the bug fix, ideally in the same commit that fixes the bug
aa1c9b	228	or adds the feature. To build and review docs, use the following steps.
49f5c4	229
eadaee	230	1. In the main Pyramid checkout directory, run `tox -e docs`:
995155	231
eadaee	232	$ tox -e docs
995155	233
081699	234	2. Open the `docs/_build/html/index.html` file to see the resulting HTML
c7fcdf	235	rendering.
84b496	236
319806	237
49f5c4	238	Change Log
CM	239	----------
	240
081699	241	- Feature additions and bugfixes must be added to the `CHANGES.rst`
49f5c4	242	file in the prevailing style. Changelog entries should be long and
CM	243	descriptive, not cryptic. Other developers should be able to know
	244	what your changelog entry means.