expo/expoweb
1
0
Fork 0
mirror of https://expo.survex.com/repositories/expoweb/.git/ synced 2024-11-22 15:21:55 +00:00
Code Issues Packages Projects Releases Wiki Activity
98546eb0a3
expoweb/handbook/computing/contribute.html

176 lines
9.5 KiB
HTML
Raw Blame History

<!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="0/cave/qms/1623-291">obvious gap in the cross-referencing</a> and would like to fix it.
<h3 id="surveydata">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="/cave/scans/1623-291">the scans of raw survey data</a> or the
<a href="/expedition/2019#trips">the equivalent logbook records of trips</a>
for those dates.
<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 id="programming">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://masteringdjango.com/django-tutorials/mastering-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="surveylaptop.html">survey 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).
<h3>Your laptop</h3>
<p>
Your own laptop + web-browser is already a <a href="basiclaptop.html">basic expo machine</a>.
You will need to install cave survey software to make it a
then <a href="surveylaptop.html">a survey laptop</a>. This
can take an hour or so, 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>.
Once you have got a bit of experience with the how expo works, you can upgrade your laptop
to a <a href="bulupdatelaptop.html">bulk update machine</a>.
If you really want to get stuck into the code you will need a <a href="../troggle/troglaptop.html">troggle software development configuration</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/trogtests.html">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>
Reference in New Issue View Git Blame Copy Permalink