expo/expoweb
1
0
Fork 0
mirror of https://expo.survex.com/repositories/expoweb/.git/ synced 2024-11-21 14:51:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

How can I contribute ?

Browse Source
This commit is contained in:
Philip Sargent 2020-07-25 22:39:00 +01:00
parent b090264951
commit d95558c84f
5 changed files with 218 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
copyit.htm
View File

@ -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
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
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
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
as objective, accurate and up-to-date as possible; but we cannot make any
guarantee that this has been achieved; please see the <a

169
handbook/computing/contribute.html Normal file
View 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>

1
handbook/index.htm
View File

@ -45,6 +45,7 @@ Need to get in touch with someone? Look here.
<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!
<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="uploading.html">Uploading photos</a> - More detailed description on photos management.</li>

41
handbook/troggle/unittests.html Normal file
View 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>

1
infodx.htm
View File

@ -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/rig/rigit.html">Rigging 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.
</ul>