|
| 1 | +<div align="center"> |
| 2 | + |
| 3 | +<img src="media/docs/ietf-datatracker-logo.svg" alt="IETF Datatracker" width="600" /> |
| 4 | + |
| 5 | +[](https://github.com/ietf-tools/datatracker/releases) |
| 6 | +[](https://github.com/ietf-tools/datatracker/blob/main/LICENSE) |
| 7 | + |
| 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