Skip to content

Commit a9fd21e

Browse files
author
nick
committed
misc: new README.md + docker dir cleanup
Commit ready for merge. - Legacy-Id: 19793
1 parent 54fc036 commit a9fd21e

8 files changed

Lines changed: 220 additions & 487 deletions

File tree

PLAN

Lines changed: 0 additions & 1 deletion
This file was deleted.

README-CDN.rst

Lines changed: 0 additions & 183 deletions
This file was deleted.

README.datatracker

Lines changed: 0 additions & 35 deletions
This file was deleted.

README.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
<div align="center">
2+
3+
<img src="media/docs/ietf-datatracker-logo.svg" alt="IETF Datatracker" width="600" />
4+
5+
[![Release](https://img.shields.io/github/release/ietf-tools/datatracker.svg?style=flat&maxAge=3600)](https://github.com/ietf-tools/datatracker/releases)
6+
[![License](https://img.shields.io/badge/license-BSD3-blue.svg?style=flat)](https://github.com/ietf-tools/datatracker/blob/main/LICENSE)
7+
![Nightly DB Build](https://img.shields.io/github/workflow/status/ietf-tools/datatracker/dev-db-nightly?label=Nightly%20DB%20Build&style=flat&logo=docker&logoColor=white&maxAge=3600)
8+
9+
##### The day-to-day front-end to the IETF database for people who work on IETF standards.
10+
11+
</div>
12+
13+
- [**Production Website**](https://datatracker.ietf.org)
14+
- [Getting Started](#getting-started)
15+
- [Prerequisites](#prerequisites)
16+
- [Code Tree Overview](#code-tree-overview)
17+
- [Adding a New Web Page](#adding-a-new-web-page)
18+
- [Testing your work](#testing-your-work)
19+
- [Docker Dev Environment](#docker-dev-environment)
20+
- [Continuous Integration](#continuous-integration)
21+
- [Database & Assets](#database--assets)
22+
23+
---
24+
25+
### Getting Started
26+
27+
This project is following the standard **Git Feature Workflow with Develop Branch** development model. Learn about all the various steps of the development workflow, from creating a fork to submitting a pull request, in the [Contributing](CONTRIBUTING.md) guide.
28+
29+
> Make sure to read the [Styleguides](CONTRIBUTING.md#styleguides) section to ensure a cohesive code format across the project.
30+
31+
You can submit bug reports, enhancement and new feature requests in the [discussions](https://github.com/ietf-tools/datatracker/discussions) area. Accepted tickets will be converted to issues.
32+
33+
#### Prerequisites
34+
35+
- Python 3.6
36+
- Django 2.x
37+
- Node.js 16.x
38+
- MariaDB 10
39+
40+
> See the [Docker Dev Environment](#docker-dev-environment) section below for a preconfigured docker environment.
41+
42+
#### Code Tree Overview
43+
44+
The `ietf/templates/` directory contains Django templates used to generate web pages for the datatracker, mailing list, wgcharter and other things.
45+
46+
Most of the other `ietf` sub-directories, such as `meeting`, contain the python/Django model and view information that go with the related templates. In these directories, the key files are:
47+
48+
| File | Description |
49+
|--|--|
50+
| urls.py | binds a URL to a view, possibly selecting some data from the model. |
51+
| models.py | has the data models for the tool area. |
52+
| views.py | has the views for this tool area, and is where views are bound to the template. |
53+
54+
#### Adding a New Web Page
55+
56+
To add a new page to the tools, first explore the `models.py` to see if the model you need already exists. Within `models.py` are classes such as:
57+
58+
```python
59+
class IETFWG(models.Model):
60+
ACTIVE = 1
61+
group_acronym = models.ForeignKey(Acronym, primary_key=True, unique=True, editable=False)
62+
group_type = models.ForeignKey(WGType)
63+
proposed_date = models.DateField(null=True, blank=True)
64+
start_date = models.DateField(null=True, blank=True)
65+
dormant_date = models.DateField(null=True, blank=True)
66+
...
67+
```
68+
69+
In this example, the `IETFWG` class can be used to reference various fields of the database including `group_type`. Of note here is that `group_acronym` is the `Acronym` model so fields in that model can be accessed (e.g., `group_acronym.name`).
70+
71+
Next, add a template for the new page in the proper sub-directory of the `ietf/templates` directory. For a simple page that iterates over one type of object, the key part of the template will look something like this:
72+
73+
```html
74+
{% for wg in object_list %}
75+
<tr>
76+
<td><a href="{{ wg.email_archive }}">{{ wg }}</a></td>
77+
<td>{{ wg.group_acronym.name }}</td>
78+
</tr>
79+
{% endfor %}
80+
```
81+
In this case, we're expecting `object_list` to be passed to the template from the view and expecting it to contain objects with the `IETFWG` model.
82+
83+
Then add a view for the template to `views.py`. A simple view might look like:
84+
85+
```python
86+
def list_wgwebmail(request):
87+
wgs = IETFWG.objects.all();
88+
return render_to_response('mailinglists/wgwebmail_list.html', {'object_list': wgs})
89+
```
90+
The selects the IETFWG objects from the database and renders the template with them in object_list. The model you're using has to be explicitly imported at the top of views.py in the imports statement.
91+
92+
Finally, add a URL to display the view to `urls.py`. For this example, the reference to `list_wgwebmail` view is called:
93+
94+
```python
95+
urlpatterns += patterns('',
96+
...
97+
(r'^wg/$', views.list_wgwebmail),
98+
)
99+
```
100+
101+
#### Testing your work
102+
103+
Assuming you have the database settings configured already, you can run the server locally with:
104+
105+
```sh
106+
$ ietf/manage.py runserver localhost:<port>
107+
```
108+
where `<port>` is arbitrary. Then connect your web browser to `localhost:<port>` and provide the URL to see your work.
109+
110+
When you believe you are ready to commit your work, you should run the test suite to make sure that no tests break. You do this by running
111+
112+
```sh
113+
$ ietf/manage.py test --settings=settings_sqlitetest
114+
```
115+
116+
### Docker Dev Environment
117+
118+
In order to simplify and reduce the time required for setup, a preconfigured docker environment is available.
119+
120+
Read the [Docker Dev Environment](docker/README.md) guide to get started.
121+
122+
### Continuous Integration
123+
124+
*TODO*
125+
126+
### Database & Assets
127+
128+
Nightly database dumps of the datatracker are available at
129+
https://www.ietf.org/lib/dt/sprint/ietf_utf8.sql.gz
130+
131+
> Note that this link is provided as reference only. To update the database in your dev environment to the latest version, you should instead run the `docker/cleandb` script!
132+
133+
Additional data files used by the datatracker (e.g. instance drafts, charters, rfcs, agendas, minutes, etc.) are available at
134+
https://www.ietf.org/standards/ids/internet-draft-mirror-sites/
135+
136+
> A script is available at `docker/scripts/app-rsync-extras.sh` to automatically fetch these resources via rsync.

0 commit comments

Comments
 (0)