Skip to content

Commit 994d1d1

Browse files
chryswoodschryswoods
committed
Working on the tutorial first (tutorial-driven development). While thinking
cleaned up the snag that the packaging info was out of date
1 parent bd27ad8 commit 994d1d1

File tree

6 files changed

+270
-52
lines changed

6 files changed

+270
-52
lines changed

‎PACKAGING.md

+4-52
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,6 @@
1-
# Instructions for packaging MetaWards
1+
# Developing and packaging MetaWards
22

3-
First create a Git tag using;
4-
5-
```
6-
git tag -a {VERSION} -m "Message"
7-
```
8-
9-
e.g.
10-
11-
```
12-
git tag -a 0.3.0b -m "Beta release of 0.3.0"
13-
```
14-
15-
then push your tag to GitHub
16-
17-
```
18-
git push --tags
19-
```
20-
21-
The tag will be used by automatic versioning script to generate
22-
the version numbers of the code. Building the package
23-
(as happens below) will automatically update the _version.py
24-
that is included in the package to tag versions.
25-
26-
## Creating the pip package
27-
28-
To create the pip package and upload to pypi type;
29-
30-
```
31-
python3 -m pip install --user --upgrade setuptools wheel
32-
```
33-
34-
Now run this command from the same directory where setup.py is located
35-
36-
```
37-
CYTHONIZE=1 python3 setup.py sdist bdist_wheel
38-
```
39-
40-
Now ensure you have the latest version of twine installed
41-
42-
```
43-
python3 -m pip install --user --upgrade twine
44-
```
45-
46-
Next upload to pypi, using
47-
48-
```
49-
python3 -m twine upload dist/*
50-
```
51-
52-
Note you will need a username and password for pypi and to have
53-
permission to upload code to this project.
3+
MetaWards is now fully tested and deployed using GitHub actions.
544

5+
Full instructions for packaging are
6+
[available here](https://metawards.org/packaging.html).

‎doc/source/images/github_artifacts.jpg

185 KB
Loading

‎doc/source/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ Contributing
107107
:maxdepth: 2
108108

109109
contributing
110+
packaging
110111

111112
Documentation
112113
=============

‎doc/source/packaging.rst

+244
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
==================
2+
Packaging releases
3+
==================
4+
5+
MetaWards is now fully tested and deployed using GitHub actions.
6+
The development process should be;
7+
8+
* New features are developed on feature branches, called ``feature-{feature}``,
9+
either in the `main MetaWards repository <https://github.com/metawards/MetaWards>`__
10+
for authorised developers, or in personal forks for
11+
new developers.
12+
* Bug fixes or issue fixes are developed on fix branches, called
13+
``fix-issue-{number}`` (again in either the main repository or forks).
14+
* Pull requests are issued from these branches to ``devel``. All merge conflicts
15+
must be fixed in the branch and all tests must pass before the pull
16+
request can be merged into ``devel``. NOTE THAT ONLY AUTHORISED
17+
DEVELOPERS CAN ACCEPT THE PULL REQUEST. Authorised developers will
18+
review the pull request as quickly as they can. They will be greatly
19+
helped if the feature is accompanied with tests, examples and/or tutorial
20+
instructions, and if most changes are confined to plugins
21+
(e.g. :mod:`metawards.iterators`, :mod:`metawards.extractors`,
22+
:mod:`metawards.mixers` or :mod:`metawards.movers`).
23+
24+
The result of this is that "devel" should contain the fully-working and
25+
tested, and most up-to-date version of ``metawards``. However, this
26+
version should not be used for production runs.
27+
28+
.. note::
29+
30+
The group of developers authorised to have access to the
31+
`main MetaWards repository <https://github.com/metawards/MetaWards>`__
32+
and to accept pull requests is not fixed,
33+
and will evolve over time. If you wish to join this group then
34+
please complete the tutorial and then demostrate your commitment
35+
by submitting good issues and pull requests from
36+
a personal fork of the repository. Please get in touch if you find
37+
this difficult, or follow
38+
`this workshop <https://chryswoods.com/beginning_git>`__ if you need
39+
to learn how to use Git, GitHub, feature branching, merging, pull
40+
requests etc.
41+
42+
Defining a release
43+
------------------
44+
45+
We will release ``metawards`` regularly. Releases aim to be backwards
46+
compatible and capable of being used for production runs, at least for
47+
the functionality that is fully described in the tutorial.
48+
49+
We use `semantic versioning <https://semver.org>`__ and take care
50+
not to cause breaking changes in the public API. The public API
51+
consists of the core :mod:`metawards` module only - it does not
52+
cover :mod:`metawards.utils` or any plugins that are in
53+
:mod:`metawards.iterators`, :mod:`metawards.extractors`,
54+
:mod:`metawards.mixers` or :mod:`metawards.movers` (although,
55+
the core plugin interface API will not change). We will
56+
endeavour to retain backwards compatibility outside of
57+
the core :mod:`metawards` module, but cannot guarantee it.
58+
59+
.. note::
60+
61+
It is the job of the release manager (currently
62+
`chryswoods <https://github.com/chryswoods>`__) to decide when it is time
63+
to create a new release. If you are interested in helping join the release
64+
management group then please feel free to get in touch.
65+
66+
Creating a release
67+
------------------
68+
69+
To create a release first checkout the "master" branch.
70+
71+
.. code-block:: bash
72+
73+
git checkout master
74+
git pull
75+
76+
Next, merge in all changes from the "devel" branch.
77+
78+
.. code-block:: bash
79+
80+
git pull origin devel
81+
82+
Next, update the :doc:`changelog` with details about this release. This
83+
should include the link at the top of the release that shows the commit
84+
differences between versions. This can be easily copied from a previous
85+
release and updated, e.g.
86+
87+
::
88+
89+
`0.11.2 <https://github.com/metawards/MetaWards/compare/0.11.1...0.11.2>`__ - May 11th 2020
90+
91+
92+
could be changed to
93+
94+
::
95+
96+
`0.12.0 <https://github.com/metawards/MetaWards/compare/0.11.2...0.12.0>`__ - May 15th 2020
97+
98+
when moving from the 0.11.2 to 0.12.0 release.
99+
100+
Now push this change back to GitHub, using;
101+
102+
.. code-block:: bash
103+
104+
git push
105+
106+
This will trigger a CI/CD run which will build and test everything on
107+
Windows, Mac and Linux for Python 3.7 and 3.8. Everything should work,
108+
as "devel" should have been in a release-ready state.
109+
110+
Testing the packages
111+
--------------------
112+
113+
`GitHub actions <https://github.com/metawards/MetaWards/actions>`__ will
114+
produce the source and binary wheels for ``metawards`` on all supported
115+
platforms. This will be in an artifact called ``dist`` which you should
116+
download and unpack.
117+
118+
.. image:: images/github_artifacts.jpg
119+
:alt: Image of the GitHub Actions interface showing the dist artifact
120+
121+
You should unpack these into the ``dist`` directory, e.g.
122+
123+
.. code-block:: bash
124+
125+
cd dist
126+
unzip ~/Downloads/dist.zip
127+
128+
This should result in six binary wheels and once source package, e.g.
129+
130+
::
131+
132+
metawards-0.11.1+7.g52b3671-cp37-cp37m-macosx_10_14_x86_64.whl
133+
metawards-0.11.1+7.g52b3671-cp37-cp37m-manylinux1_x86_64.whl
134+
metawards-0.11.1+7.g52b3671-cp37-cp37m-win_amd64.whl
135+
metawards-0.11.1+7.g52b3671-cp38-cp38-macosx_10_14_x86_64.whl
136+
metawards-0.11.1+7.g52b3671-cp38-cp38-manylinux1_x86_64.whl
137+
metawards-0.11.1+7.g52b3671-cp38-cp38-win_amd64.whl
138+
metawards-0.11.1+7.g52b3671.tar.gz
139+
140+
Try to install the package related to you machine, just to double-check
141+
that it is working, e.g.
142+
143+
.. code-block:: bash
144+
145+
pip install ./metawards-0.11.1+7.g52b3671-cp37-cp37m-macosx_10_14_x86_64.whl
146+
cd ..
147+
pytest tests
148+
149+
Once it is working, remove these temporary packages from your ``dist`` folder,
150+
151+
.. code-block:: bash
152+
153+
rm dist/*
154+
155+
Tagging a new release
156+
---------------------
157+
158+
Now that you are happy that the release is ready, you can tag the new
159+
version. Do this using the ``git tag`` command, e.g.
160+
161+
.. code-block:: bash
162+
163+
git tag -a {VERSION} -m "{VERSION} release"
164+
165+
replacing ``{VERSION}`` with the version number. For this 0.12.0 release
166+
the command would be;
167+
168+
.. code-block:: bash
169+
170+
git tag -a 0.12.0 -m "0.12.0 release"
171+
172+
Next, push your tag to GitHub;
173+
174+
.. code-block:: bash
175+
176+
git push --tags
177+
178+
The tag will be used by automatic versioning script to generate
179+
the version numbers of the code. Building the package
180+
(as happens below) will automatically update the _version.py
181+
that is included in the package to tag versions.
182+
183+
This will also trigger a full CI/CD to test and build the new version.
184+
Again, it should work as this tag was taken from your fully-tested
185+
"master" branch.
186+
187+
Uploading packages to pypi
188+
--------------------------
189+
190+
While you are waiting for the CI/CD GitHub Actions to complete, make sure
191+
that your version of twine is fully up to date;
192+
193+
.. code-block:: bash
194+
195+
pip install --upgrade twine
196+
197+
Once GitHub actions is complete, you will see that another build artifact
198+
is ready for download. Download this and unpack it into your ``dist``
199+
directory as before. You should now have a ``dist`` directory that
200+
contains six binary wheels and one source package, named according to
201+
the release version. For example, for the 0.11.2 release we had;
202+
203+
.. code-block:: bash
204+
205+
$ ls dist
206+
metawards-0.11.2-cp37-cp37m-macosx_10_14_x86_64.whl
207+
metawards-0.11.2-cp37-cp37m-manylinux1_x86_64.whl
208+
metawards-0.11.2-cp37-cp37m-win_amd64.whl
209+
metawards-0.11.2-cp38-cp38-macosx_10_14_x86_64.whl
210+
metawards-0.11.2-cp38-cp38-manylinux1_x86_64.whl
211+
metawards-0.11.2-cp38-cp38-win_amd64.whl
212+
metawards-0.11.2.tar.gz
213+
214+
Now you can upload to pypi using the command;
215+
216+
.. code-block:: bash
217+
218+
python3 -m twine upload dist/*
219+
220+
.. note::
221+
222+
You will need a username and password for pypi and to have
223+
permission to upload code to this project. Currently only
224+
the release manager has permission. If you would like
225+
join the release management team then please get in touch.
226+
227+
Testing the final release
228+
-------------------------
229+
230+
Finally(!) test the release on a range of different machines by logging
231+
in and typing;
232+
233+
.. code-block:: bash
234+
235+
pip install metawards=={VERSION}
236+
237+
replacing ``{VERSION}`` with the version number, e.g. for 0.11.2
238+
239+
.. code-block:: bash
240+
241+
pip install metawards==0.11.2
242+
243+
Play with the code, run the tests and run some examples. Everything should
244+
work as you have performed lots of prior testing to get to this stage.

‎doc/source/tutorial/index_part06.rst

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
====================================
2+
Part 6 - Moving between demographics
3+
====================================
4+
5+
In this sixth part of the tutorial you will:
6+
7+
* Understand how you can move individuals between demographics using
8+
:doc:`metawards.movers <../api/index_MetaWards_movers>`.
9+
* Use ``go functions`` to model the movement of individuals as they
10+
go into isolation, go to hospital, or go back home
11+
* Learn how to write custom movers to model holidays and quarantine
12+
13+
.. toctree::
14+
:maxdepth: 2
15+
16+
part06/01_movers

‎doc/source/tutorial/part06/01_movers.rst

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
=======================
2+
Movers and go functions
3+
=======================
4+
5+

0 commit comments

Comments
 (0)