mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-11-25 08:41:54 +00:00
How can I contribute ?
This commit is contained in:
Philip Sargent
parent
b090264951
commit
d95558c84f
@ -39,7 +39,9 @@ these organisations or the original authors direct.</p>
|
|||||||
|
|
||||||
<p>Copyright in the HTML, page layout and structure of the archive originally
|
<p>Copyright in the HTML, page layout and structure of the archive originally
|
||||||
lay with Andy Waddington, who has released anything directly attributable to
|
lay with Andy Waddington, who has released anything directly attributable to
|
||||||
his work as CC-BY-SA. More recent work on the strucure, style and mechanisms
|
his work as
|
||||||
|
<a href="https://en.wikipedia.org/wiki/Creative_Commons_license#Types_of_licenses">CC-BY-SA</a>.
|
||||||
|
More recent work on the structure, style and mechanisms
|
||||||
of maintaining the site belong to younger authors who may or may not wish
|
of maintaining the site belong to younger authors who may or may not wish
|
||||||
their work to be reproduced.</p>
|
their work to be reproduced.</p>
|
||||||
|
|
||||||
@ -68,6 +70,9 @@ members</a> for a pretty inclusive list of authors.</p>
|
|||||||
<tt>expoweb-admin</tt> on site <tt>cucc.survex.com</tt>) in the first instance
|
<tt>expoweb-admin</tt> on site <tt>cucc.survex.com</tt>) in the first instance
|
||||||
before reproducing any material.</p>
|
before reproducing any material.</p>
|
||||||
|
|
||||||
|
<p>Programming code and documentation open source licenses are described in the
|
||||||
|
"<a href="handbook/computing/contribute.html#opensource">How can I contribute?</a>" page.
|
||||||
|
|
||||||
<p>And finally ... material written specifically for this archive tries to be
|
<p>And finally ... material written specifically for this archive tries to be
|
||||||
as objective, accurate and up-to-date as possible; but we cannot make any
|
as objective, accurate and up-to-date as possible; but we cannot make any
|
||||||
guarantee that this has been achieved; please see the <a
|
guarantee that this has been achieved; please see the <a
|
||||||
|
|||||||
169
handbook/computing/contribute.html
Normal file
169
handbook/computing/contribute.html
Normal file
@ -0,0 +1,169 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||||
|
<title>Expo - How Can I Contribute?</title>
|
||||||
|
<link rel="stylesheet" type="text/css" href="../../css/main2.css" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<h2 id="tophead">CUCC Expedition Handbook - Maintenance</h2>
|
||||||
|
<h1>How Can I Contribute?</h1>
|
||||||
|
|
||||||
|
<h2>How you can help</h2><a href="../survey/why.htm"><img class="onright" src="go-caving-th.jpg"></a>
|
||||||
|
<p>
|
||||||
|
OK, you have been on expo, or are planning to go and the organisers have said
|
||||||
|
that <a href="../planning.html">they don't need any more help</a> (hah!).
|
||||||
|
We always need help maintaining the records of cave explorations. We also always
|
||||||
|
need help maintaining the software and documentation which helps us do this.
|
||||||
|
|
||||||
|
|
||||||
|
<p>Possibly you are a programmer horrified by the apparently archaic software
|
||||||
|
you have seen, possibly you just want to make sure that the work you
|
||||||
|
did has been properly recorded and
|
||||||
|
<a href="/personexpedition/BeckaLawson/2009">attributed</a>, or maybe you have
|
||||||
|
seen an <a href="/survey_scans/">obvious gap in the cross-referencing</a> and would like to fix it.
|
||||||
|
|
||||||
|
<h3>Survey Data</h3>
|
||||||
|
<p>We have a <a href="todo-data.html">Expo <em>Data</em> To-Do List</a>. If all you do is to check items on this list
|
||||||
|
and email a nerd to tell them which have already been done then that would be excellent. And if you discover any bad or missing survey data then here is where you record the problem (see "Edit this page" below).
|
||||||
|
|
||||||
|
<p>The biggest job after every expo is "tunneling": turning the typed-up survex data into drawings.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<div class="onright">
|
||||||
|
<figure>
|
||||||
|
<a href="/survey_scans/2017%252331/notes2.jpeg"><img width="200px" src="/survey_scans/2017%252331/notes2.jpeg"></a>
|
||||||
|
<br><figcaption style="font-variant-caps: small-caps;">2017 Snakecharmer in 258</figcaption>
|
||||||
|
</figure>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
|
||||||
|
<p>Cavers are usually pretty good, with some encouragement, at typing their survey notes into
|
||||||
|
<a href="/survexfile/caves-1623/2017-cucc-24/couldashouldawoulda_to_bathdodgersbypass.svx">survex
|
||||||
|
files</a> and scanning <a href="/survey_scans/2019%252305/notes1.pdf">their notes</a> and
|
||||||
|
underground sketches (in the plastic survey wallets) as scanfiles into the
|
||||||
|
<a href="/survey_scans/2019%252305/">online wallets</a>.
|
||||||
|
But the <a href="/expofiles/surveyscans/2019/walletindex.html">outstanding tasks list</a> after expo
|
||||||
|
is always much longer than we would like.
|
||||||
|
So <a href="/survexfile/291">the list of surveys attached to a cave</a> is incomplete,
|
||||||
|
as can be seen by looking at <a href="">the equivalent logbook records of trips</a> for those dates
|
||||||
|
(scroll down to the bottom of the expedition page for the calendar).
|
||||||
|
|
||||||
|
<p>There is always a backlog of surveyed caves that need their scanned centrelines annotating with
|
||||||
|
the in-cave sketches, and then re-scanning and tracing using tunnel (or therion) to produce a survey.
|
||||||
|
This is "tunneling".
|
||||||
|
|
||||||
|
<p>We also have a simpler job of editing old survex files with the correct caver names such that
|
||||||
|
old data is attributed. For example the trip to <a href="/survexfile/115">the deepest part of the SMKsystem</a>
|
||||||
|
is still not properly connected with the rest of the survey systems
|
||||||
|
because the survex data uses an old format
|
||||||
|
(this was Chaz Butcher, Andy Dolby and Pete Lancaster's trips to the Orgasm Chasm sump in 115 in 1982).
|
||||||
|
In 1999 and earlier the scanned notes and wallets are not connected to the survex files either as you can see
|
||||||
|
in the blank "survex blocks" column in <a href="/survey_scans/">the survey scans folders</a> list.
|
||||||
|
|
||||||
|
<h3>Programming</h3>
|
||||||
|
<p>The expo software system is a multi-decade long-term project. So it is probably unlike
|
||||||
|
any software projects you have been involved with. It is quite unlike other Django projects.
|
||||||
|
|
||||||
|
<a href="../troggle/trogarch.html">
|
||||||
|
<div class="onright">
|
||||||
|
<figure>
|
||||||
|
<a href="https://djangobook.com/mdj2-django-structure/"><img src="mtv_drawing2.jpg"></a>
|
||||||
|
<br><figcaption style="font-variant-caps: small-caps;">Django server and webpage (client)</figcaption>
|
||||||
|
</figure>
|
||||||
|
</div>
|
||||||
|
</a>
|
||||||
|
|
||||||
|
<p>The primary problem is lack of consistently available manpower. So modifications
|
||||||
|
have to be compact and designed to be easily maintainable by time-constrained numpties
|
||||||
|
in the future. So whatever you do has to be consistently documented (and
|
||||||
|
<a href="onlinesystems.html">in the manuals</a>, not just in the code)
|
||||||
|
otherwise it will just get thrown away by the next person.
|
||||||
|
|
||||||
|
<p>There are few "clean" little programming jobs really. Nearly everything is intimately
|
||||||
|
connected to the data formats of the expo and survey input data: survex files, tunnel files,
|
||||||
|
therion files, logbook files, cave-description XML files, entrance files, survey-scans folders
|
||||||
|
(wallets) and <a href="../survey/newcave.html">the workflow</a> of turning scruffy notes
|
||||||
|
into the finished survey documents we provide to the Austrians.
|
||||||
|
|
||||||
|
<h4>Little jobs to start with</h4>
|
||||||
|
|
||||||
|
<p>We have a <a href="todo.html">Expo <em>Systems</em> To-Do List</a>. If all you do is to test items on this list
|
||||||
|
and delete those which have already been done then that would be excellent (use the "Edit this to-do list"
|
||||||
|
big blue button on that page: and then email someone to tidy up the <a href="/repositories/">git checkin</a>
|
||||||
|
when you are done). And if you discover any bugs and - especially if you find a web page which crashes - then
|
||||||
|
here is where you record the problem.
|
||||||
|
|
||||||
|
<p>There are some simple jobs that don't require in-depth knowledge of large
|
||||||
|
parts of the system, e.g. extracting diagrams from the scanned PDF copies of the logbooks
|
||||||
|
and inserting them into the HTML version of the same logbook. There is a list of the logbooks
|
||||||
|
that need doing in the "Logbook Fettling" section of the
|
||||||
|
<a href="todo-data.html">Expo <em>Data</em> To-Do List</a>.
|
||||||
|
|
||||||
|
<p>There are broken links in the handbook which need fixing. At the bottom of the
|
||||||
|
<a href="yourlaptop.html">your laptop configuration</a> page is a list of link-checking tools.
|
||||||
|
Run one or more of these and use the <a href="hbmanual1.html">"Edit this page"</a>
|
||||||
|
capability to fix the handbook pages
|
||||||
|
so that the links work. This is a perennial problem with external websites which change their
|
||||||
|
hosting systems and domain names too frequently for us to keep up with.
|
||||||
|
|
||||||
|
<h4>Bigger jobs</h4>
|
||||||
|
|
||||||
|
<a href="../survey/newcave.html">
|
||||||
|
<div class="onright">
|
||||||
|
<figure>
|
||||||
|
<a href="../l/life-wallet.html">
|
||||||
|
<img src="../t/life-wallet.jpg"></a>
|
||||||
|
<figcaption style="font-variant-caps: small-caps;">
|
||||||
|
<em>The things you do with a wallet</em>
|
||||||
|
</figcaption>
|
||||||
|
</figure>
|
||||||
|
</div>
|
||||||
|
</a>
|
||||||
|
<p>Before starting any coding you will need to have a good general feel for what the input data is
|
||||||
|
and how it is handled. So please, please do a couple of data management jobs first -
|
||||||
|
as described in the 'Survey Data' section above.
|
||||||
|
|
||||||
|
<p>Many of the items on the Systems To-Do list won't make much sense until you have read
|
||||||
|
through the <a href="../troggle/trogarch.html">expo systems architecture</a> documents,
|
||||||
|
and before you plan some changes have a look
|
||||||
|
at the <a href="../troggle/trogdesign.html">design decisions and proposals documents</a>
|
||||||
|
of the things we are already thinking about. And before you do anything, please do contribute
|
||||||
|
a page or two on what you think would be a good idea (using the handbook editing
|
||||||
|
<a href="hbmanual1.html">"Edit this page"</a> capability to
|
||||||
|
add a new design document).
|
||||||
|
<p>
|
||||||
|
Before you do anything substantial you will probably need to
|
||||||
|
<a href="basiclaptop.html">set up a minimal expo machine</a> and
|
||||||
|
then <a href="yourlaptop.html">set up a full configuration</a>. This
|
||||||
|
can take nearly a full day even if you are moderately competent at
|
||||||
|
configuring a Linux machine, but you don't need to install everything before
|
||||||
|
you can contribute to fixing things in the <a href="todo.html">Expo <em>Systems</em> To-Do List</a>.
|
||||||
|
|
||||||
|
<p>Finally, if that all sounds like too much hassle for you, were are in desparate need
|
||||||
|
of a lot more very simple <a href="../troggle/unittests.html">unit tests for troggle</a>.
|
||||||
|
The more tests we have, the more confident we can be
|
||||||
|
about making big changes without breaking things. We especially need these for the input parsers
|
||||||
|
as whatever happens in the future, we are still going to need to parse the archived input files.
|
||||||
|
|
||||||
|
<h4 id="opensource">Copyright and open source</h4>
|
||||||
|
<a href="https://www.cam.ac.uk/brand-resources/trademark-and-licensing">
|
||||||
|
<img class="onright" width=150px" src="https://www.cam.ac.uk/sites/www.cam.ac.uk/files/inner-images/logo.jpg">
|
||||||
|
</a>
|
||||||
|
<p>By contributing code and documentation to the expo systems you are assigning copyright under the
|
||||||
|
<a href="https://en.wikipedia.org/wiki/MIT_License">OSI MIT</a>
|
||||||
|
open source license to CUCC (Cambridge University Caving Club). Note that Troggle is built with Django which uses the
|
||||||
|
<a href="https://www.djangoproject.com/trademarks/">CC-BY-SA 3.0</a> creative commons license.
|
||||||
|
Text and photographs, except where documenting code, are covered by <a href="../../copyit.htm">a
|
||||||
|
separate copyright process</a>
|
||||||
|
and by default this will be
|
||||||
|
<a href="https://en.wikipedia.org/wiki/Creative_Commons_license#Types_of_licenses">CC-BY-SA 3.0</a>.
|
||||||
|
Note that "Cambridge University" and other similar phrases are
|
||||||
|
<a href="https://www.cam.ac.uk/brand-resources/trademark-and-licensing">strictly controlled by the university</a>.
|
||||||
|
<hr />
|
||||||
|
Go on to: <a href="../troggle/trogintro.html">Troggle introduction</a><br />
|
||||||
|
Return to: <a href="onlinesystems.html">Expo systems overview</a><br />
|
||||||
|
<hr />
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
@ -45,6 +45,7 @@ Need to get in touch with someone? Look here.
|
|||||||
<h2>Computing and Cave Surveying</h2>
|
<h2>Computing and Cave Surveying</h2>
|
||||||
This is a scientific expedition - the Austrian government allows us to wander around the plateau <em>in exchange for</em> cave surveys. Learn how to contribute!
|
This is a scientific expedition - the Austrian government allows us to wander around the plateau <em>in exchange for</em> cave surveys. Learn how to contribute!
|
||||||
<ul>
|
<ul>
|
||||||
|
<li><a style="color: blue" href="computing/contribute.html">How can I contribute?</a> - there's lots you can help with now, even before you come on your first expo.</li>
|
||||||
<li><a href="computing/onlinesystems.html">Expo online systems</a> - Overview of expo server capabilites.</li>
|
<li><a href="computing/onlinesystems.html">Expo online systems</a> - Overview of expo server capabilites.</li>
|
||||||
|
|
||||||
<li><a href="uploading.html">Uploading photos</a> - More detailed description on photos management.</li>
|
<li><a href="uploading.html">Uploading photos</a> - More detailed description on photos management.</li>
|
||||||
|
|||||||
41
handbook/troggle/unittests.html
Normal file
41
handbook/troggle/unittests.html
Normal file
@ -0,0 +1,41 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||||
|
<title>Handbook Troggle - Unit Tests</title>
|
||||||
|
<link rel="stylesheet" type="text/css" href="../../css/main2.css" />
|
||||||
|
</head>
|
||||||
|
<body><style>body { background: #fff url(/images/style/bg-system.png) repeat-x 0 0 }</style>
|
||||||
|
<h2 id="tophead">CUCC Expedition Handbook</h2>
|
||||||
|
<h1>Handbook Troggle - Unit Tests</h1>
|
||||||
|
|
||||||
|
<h2>Troggle Unit Tests</h2>
|
||||||
|
<p>We have a small suite of tests which are run manually by troggle programmers like this:
|
||||||
|
<pre><code> troggle$ python manage.py tests -v 1</code></pre>
|
||||||
|
The test code is all in <a href="http://expo.survex.com/repositories/troggle/.git/tree/core/TESTS/tests.py"><var>troggle/core/TESTS/tests.py</var></a>.
|
||||||
|
<p>The test 'test_page_expofile' checks that a particular PDF is being served correctly by the web server
|
||||||
|
and that the resulting page is the correct length of 2,299,270 bytes:
|
||||||
|
|
||||||
|
<pre><code>
|
||||||
|
def test_page_expofile(self):
|
||||||
|
# Flat file tests.
|
||||||
|
response = self.client.get('/expofiles/documents/surveying/tunnel-loefflerCP35-only.pdf')
|
||||||
|
self.assertEqual(response.status_code, 200)
|
||||||
|
self.assertEqual(len(response.content), 2299270)
|
||||||
|
</code></pre>
|
||||||
|
|
||||||
|
<p>This test suite is part of <a href="https://docs.djangoproject.com/en/1.11/topics/testing/">the
|
||||||
|
django test system</a> which is a very thin layer on top of the standard python library module
|
||||||
|
<a href="https://docs.python.org/3/library/unittest.html#module-unittest">unittest</a>. One of the things this layer does
|
||||||
|
is to ensure that all the settings are imported correctly, and it sets up a very fast in-memory sqlite database purely for tests.
|
||||||
|
No tests are run with the real expo database.
|
||||||
|
<p>The tests can be run at a more verbose level by setting the <var>-v 3</var> flag.
|
||||||
|
|
||||||
|
<p>As yet we have no test database set up, so the in-memory database is entirely empty.
|
||||||
|
|
||||||
|
<hr />
|
||||||
|
Go on to: <a href="trogarch.html">Troggle architecture</a><br />
|
||||||
|
Return to: <a href="trogintro.html">Troggle intro</a><br />
|
||||||
|
<hr />
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
@ -87,6 +87,7 @@ the Prospecting, Surveying, GPS, Rigging and How To Expo.</li>
|
|||||||
<li><a href="handbook/essentials.html">Essential GPS in the mountains</a>
|
<li><a href="handbook/essentials.html">Essential GPS in the mountains</a>
|
||||||
<li><a href="handbook/rig/rigit.html">Rigging guide</a>
|
<li><a href="handbook/rig/rigit.html">Rigging guide</a>
|
||||||
<li><a href="handbook/planning.html">Expo Planning Guide</a> -
|
<li><a href="handbook/planning.html">Expo Planning Guide</a> -
|
||||||
|
<li><a style="color: blue" href="handbook/computing/contribute.html">How can I contribute?</a> -
|
||||||
How to plan and make an expo happen.
|
How to plan and make an expo happen.
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user