Skip to content

Commit

Permalink
update instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@holtzermann17
holtzermann17 committed Jun 16, 2015
1 parent 1f4e2cc commit ef89758
Showing 1 changed file with 107 additions and 59 deletions.
166 changes: 107 additions & 59 deletions INSTRUCTIONS.md
View file
Original file line number Diff line number Diff line change
@@ -1,114 +1,162 @@
To use the BibProject code, check out the code from github:
# The basic idea

This repository helps distribute the task of managing public
biographic profiles of members of the Institute of Mathematical
Stastics (IMS). TeX files containing biographical data can be updated
remotely by IMS members or their representatives, and changes will be
pulled in here once they are approved by the IMS editor. The
information can then be moved to the IMS website.

## Tips on formatting TeX files

TeX files should be written following the standard outlined in the
accompanying [user docs](https://github.com/maddyloo/miniBibServer/raw/master/docs/imscv-style.pdf).

## Webpage for testing for IMS members

http://ims.metameso.org/ is a webpage that can be used by IMS members
to test their TeX files and see the generated HTML.

# For the IMS editor

To use the BibProject code locally, check out the code from github:

```sh
git clone [email protected]:BioBib/BibProject.git
```

The first thing to look at is:
[`index.txt`](https://github.com/BioBib/BibProject/blob/master/index.txt).

(Note, this file can be edited over the web if you find that simpler.
Some other interaction steps described below require the use of the
web interface. However, for now, these instructions proceed under the
assumption that you are using a command line version of Git for
editing purposes. The actual underlying operations are essentially
the same in either case.)

# The automated component

A script runs every day at 1AM UK time, via the following crontab
entry in joe's directory on li311-58.members.linode.com:

```
0 1 * * * python /bibserver/ims_legacy/scan-and-update.py
```

I've copied `scan-and-update.py` into the BibProject github repository
so that you can see what it does. It's the central piece of plumbing
in the miniBibServer project -- it facilitates distributed updating of
a shared Github repository.
Its facilitates distributed updating of this Github repository.

The first thing it does when it runs is it pulls in the latest version
of `ims_sources.py` from the BibProject repository to the server on
which the update process runs. It then starts reading the URLs stored
there. The `ims_sources.py` file will be the IMS Editor's first point
of control. Let's have a look at the [`ims_sources.py`](https://github.com/BioBib/BibProject/blob/master/ims_sources.py#L33) file now.
of `index.txt` from the BibProject repository to the server where it
runs. It then starts reading the paths and URLs stored in this file,
and makes pull requests when these differ from the content in the
`master` branch. All of this will become more clear later on in
these instructions.

# Maintaining the index

You'll see that there is a very long list of IMS members, and most of
them are currently associated to files that are stored in the Git
Let's have a look at the
[`index.txt`](https://github.com/BioBib/BibProject/blob/master/index.txt#L33)
file now.

You'll see that there is a very long list of IMS member IDs, and most
of them are currently associated to files that are stored in the Git
repository, specifically in the `./tex_files` directory). For
illustrative purposes, *one* of the members is associated to a tex
file stored separately on my webpage, as you'll see on [line
33](https://github.com/BioBib/BibProject/blob/master/ims_sources.py#L33)
illustrative purposes, the last line is a fictitious person, who is
associated to a tex file stored separately on my webpage,
[line 1080](https://github.com/BioBib/BibProject/blob/master/ims_sources.py#L33)
of the file:

```python
["Aitken, Alexander C.", "http://metameso.org/~joe/aitken.tex"],
```
public__john_q http://metameso.org/~joe/jqp.tex
```

The IMS editor can update this file to associate any of the tex
sources with remote URLs, in general maintained by IMS members or
their representatives. Try that now, by (1) copying a tex file from
the `./tex_files` directory to some publicly-accessible webpage that
you control, and (2) changing the corresponding entry in
`ims_sources.py`.
sources with remote URLs (or to point back to files in this repository).
Remote files will typically be maintained by IMS members or their representatives.

Try that now, by

1. Copying a tex file from the `./tex_files` directory to some
publicly-accessible webpage that you control, and
2. Changing the corresponding entry in `index.txt` to point to that
URL.

Below, I call the file you've put on your webpage the "remote file."
You can also use a `%` sign at the beginning of the line to add
comments or to comment out entries (you will eventually want to remove
the illustrative entry for "John Q. Public").

In order to make this remote file accessible to the process, **update
the corresponding entry** in `ims_sources.py` and then add, commit,
and push the updated `ims_sources.py` file to Github:
# Working with Git and Github

I call the example file you've put on your own webpage the "remote
file."

In order to make the updated index accessible to the server, you must
add, commit, and push the file to Github.

```
git add ims_sources.py
git commit -m "Adding another demo member"
git commit -m "A demonstration of remote editing."
git push
```

The next time the `scan-and-update.py` script runs, it will find the
.tex source for that member on the webpage where you put it. It will
check to see if it is different from the most current version stored
in the repository. (If you haven't changed the remote file, the
script won't find any difference, and nothing will happen. So, go
ahead and make a change to the file now, even if it's just adding in a
new `%`'ed comment. You don't have to update the Github repository
again, because it already knows where to look for this file.)

The next time `scan-and-update.py` runs, it will create a new branch
in the BibProject repository, along with a pull request addressed to
the maintainer of the BioBib/BibProject repository. The IMS editor
can then process this request using the Github web interface. This is
the editor's second point of control.
in the repository.

If you haven't changed the remote file, the script won't find any
difference, and nothing will happen. So, go ahead and make a change
to the file now, even if it's just adding in a new `%`'ed comment
line. You don't have to update the Github repository again, because
it already knows where to look for this file.

When `scan-and-update.py` notices that the file has changed, it will
create a new branch in the BibProject repository, along with a pull
request addressed to the maintainer of the BioBib/BibProject
repository. The IMS editor can then process this request using the
Github web interface. This is the editor's second point of control in
addition to the index.

Assuming the change is agreeable, the request can be merged in
directly. If the change is *not* agreeable, then the editor should
contact the person maintaining the webpage in question, and sort out
an agreed version with them.
reject it, and contact the person maintaining the webpage in question,
and sort out an agreed version with them.

As a temporary measure, if desired, the editor can modify the
corresponding entry in `ims_sources.py` to point to the relevant file
in `./tex_files`, so that the system doesn't poll the unwanted remote
corresponding entry in `index.txt` to point to the relevant file in
`./tex_files`, so that the system doesn't poll the unwanted remote
file until the discrepancy has been addressed.

The logic of the update script is such that if an IMS Member makes
further changes to their remote file before the IMS Editor has time to
update the repository, these changes will all be accumulated into the
same pull request. If days go by without the IMS Editor taking
action, and without any new changes from the IMS member, only the
original change will appear.
update the repository, these changes will be accumulated into the same
pull request.

Notifications of updates will be sent to jimpitman00 and holtzermann17
via the email service. The recipients can be adjusted at:
Notifications of updates to this repository are currently sent to
jimpitman00 and holtzermann17 via the email service. The recipients
can be adjusted at:

https://github.com/BioBib/BibProject/settings/hooks
> https://github.com/BioBib/BibProject/settings/hooks
Finally, note that HTML versions of the files are generated and
included in the `./new_html_files` directory. The intention is that
the contents of this directory can be used directly in the IMS site.
The contents are accessible anywhere via a `git clone` and `git pull`,
or this could be automated (as with the process described in this
note).

## Reminder of Webpage for testing for IMS members

http://ims.metameso.org/ is a webpage that can be used by IMS members
to test their TeX files and see the generated HTML.
The contents are accessible anywhere via a `git clone` and can be
updated with `git pull` -- or this could be automated via cron.

## One further thing to mention about testing for the IMS editor
## For testing purposes

For testing purposes, feel free to run these commands to run the scan
and update process without waiting 24 hours:
Feel free to run these commands to run the scan and update process
without waiting 24 hours:

```
ssh [email protected]
ssh [email protected] [enter password]
cd /bibserver/
python ./ims_legacy/scan-and-update.py
```

Or contact me for assistance.

-- Joe Corneli (`[email protected]`).

0 comments on commit ef89758

Please sign in to comment.