FIND-81:add initial docs-contributing,project conventions,etc

docs/developer-guide/backend.md

@@ -0,0 +1,8 @@
+# Backend development
+
+Specific guidance for working on backend tasks.
+
+## Backend resources
+
+- [The National Archives base Docker images](<https://github.com/nationalarchives/docker>)
+- [Digital Services Docker build actions](<https://github.com/nationalarchives/ds-docker-actions>)

docs/developer-guide/contributing.md

@@ -0,0 +1,29 @@
+# Contributing code
+
+Before contributing code, please familiarise yourself with the [Project conventions](project-conventions.md).
+
+## General advice
+
+- Submit pull-requests sooner rather than later: CI feedback is your friend, not your enemy.
+- Mark in-progress PRs as drafts until they are ready for review.
+- Don't be afraid to show your working. We're all learning. If you need help, linking to code changes in a PR is a quick and easy way to explain the problem.
+- Where possible, a feature branch should be kept up-to-date with `main` by regularly merging `main` into the feature branch. This will help to prevent conflicts when merging the feature branch back into `main`, and ensure there are no inconsistencies.
+
+## Submitting a pull request (PR)
+
+1. Push your branch to the remote.
+2. Head to <https://github.com/nationalarchives/ds-search/pulls> and create a pull request from your branch.
+
+   For the PR Title:
+
+   - For ticketed features or ticketed bugs, use the naming convention: `FIND-XXX: Short description`
+   - For housekeeping tasks or other unticketed work, use the convention: `CHORE: Short description`
+
+   See [here](project-conventions.md#naming-pull-requests) for more information on naming conventions.
+
+3. To mark a PR as a draft, click the drop-down where it says **"Create pull request"** and select the **"Create draft pull request"** button instead.
+4. When you are finished (and CI is passing): Add a useful description, mark the PR as "Ready to review", and request a review from another developer.
+
+## Merging a branch ?
+
+Please see [here](project-conventions.md#merging-branches) for guidance on merging branches.

docs/developer-guide/dependency-management.md

@@ -0,0 +1,49 @@
+# Dependency management
+
+Using the dev container should give you access to commands to update poetry which should update the `pyproject.toml` and/or `poetry.lock` files ready to commit to version control.
+
+## Updating build numbers
+
+e.g. `x.y.1` -> `x.y.2`
+
+1. Run `docker compose exec dev poetry update` (Python)
+
+## Major or minor numbers
+
+e.g. `x.1.z` -> `x.2.z` or `1.y.z` -> `2.y.z`
+
+- Update version numbers in `pyproject.toml` (Python)
+- Run `docker compose exec dev poetry update` (Python)
+
+## Adding a dependency
+
+Use the following to automatically use the latest version (e.g. [pendulum](https://pypi.org/project/pendulum/)):
+
+```sh
+docker compose exec dev poetry add DateTime
+docker compose exec dev poetry update
+```
+
+Or, specify a version:
+
+```sh
+docker compose exec dev poetry add DateTime@4.1.1
+docker compose exec dev poetry add "DateTime@>=4.0"
+docker compose exec dev poetry update
+```
+
+Or, to a group
+
+```sh
+docker compose exec dev poetry add --group <group-name> <package-name>
+docker compose exec dev poetry update
+```
+
+See the [Poetry docs](https://python-poetry.org/docs/cli/#add) for more options.
+
+### Removing a dependency
+
+```sh
+docker compose exec dev poetry remove DateTime
+docker compose exec dev poetry update
+```

docs/developer-guide/frontend.md

@@ -0,0 +1,9 @@
+# Frontend development
+
+Specific guidance for working on fronend tasks.
+
+## Frontend resources
+
+- [TNA Frontend](<https://github.com/nationalarchives/tna-frontend>)
+- [TNA Frontend Jinja templates](<https://github.com/nationalarchives/tna-frontend-jinja>)
+- [The National Archives Design System](<https://nationalarchives.github.io/design-system/>)

docs/developer-guide/local-development-gotchas.md

@@ -0,0 +1,3 @@
+# Local development gotchas
+
+This page lists common local development issues and how do resolve them.

docs/developer-guide/project-conventions.md

@@ -0,0 +1,59 @@
+# Project conventions
+
+At TNA we follow a set of conventions for our projects to ensure consistency and quality across our codebases. These can be found in our [Engineering handbook](https://nationalarchives.github.io/engineering-handbook/) and should be followed when contributing to the project, as well as the guidance below.
+
+## Python
+
+This project uses a few tools to improve the consistency and quality of Python code:
+
+- [``Black``](https://black.readthedocs.io/en/stable/): An opinionated Python formatter that takes care of code formatting (so we don't have to think about it).
+- [``isort``](https://pycqa.github.io/isort/): Ensures that import statements are ordered in a consistant way accross the project.
+- [``flake8``](https://flake8.pycqa.org/en/stable/): Catches things like unused parameters, unused imports and other non-formatting related things.
+
+The easiest way to ensure the code you're contributing adheres to these standards is to find and install plugins for your code editor of choice, that will check and transparently reformat your code whenever you save changes. Standard configuration files are included in the root of the repository, which *should* be picked up and respected by such plugins.
+
+Another option is to run the `format` command from your console to apply `isort` and `Black` formatting to Python code:
+
+```console
+docker compose exec dev format
+```
+
+`flake8` will just flag things in the terminal, it will not update any code for you like `isort` or `Black`.
+
+## Git/Github conventions
+
+### Branching
+
+- Changes are developed in feature branches and submitted as pull requests via Github
+- Feature branches should always be based on: `main`
+- Create a new branch if the branch for that ticket has been merged.
+
+### Naming branches
+
+- Use only alphanumeric characters and hyphens where possible and avoid special characters.
+- Branch names for ticketed new features should follow: `feature/JIRA-TICKET-NUMBER-with-short-description`
+- Branch names for ticketed bug fixes should follow: `fix/JIRA-TICKET-NUMBER-with-short-description`
+- Branch names for housekeeping tasks or other unticketed work should follow: `chore/short-description`
+
+For example:  
+
+- `feature/UN-123-extra-squiggles`
+- `fix/DF-999-image-view-error`
+- `chore/update-documentation`
+
+### Naming pull requests
+
+- Pull requests for features and bug fixes should be titled: `JIRA-TICKET-NUMBER: short-description`
+- Pull requests for housekeeping tasks or other unticketed work should be titled: `CHORE: short-description`
+
+For example:
+
+- `UN-123: Add extra squiggles`
+- `DF-999: Fix image view error`
+- `CHORE: Update documentation`
+
+### Merging branches
+
+**NOTE:** Where possible, a feature branch should be kept up-to-date with `main` by regularly merging `main` into the feature branch. This will help to prevent conflicts when merging the feature branch back into `main`, and ensure there are no inconsistencies.
+
+- When merging a feature branch into `main`, use the `Squash and merge` option to keep the commit history clean

docs/index.md

@@ -1 +1,15 @@
-# Welcome
+# DS Search Technical Documentation
+
+## Project overview
+
+Provides search funtionality to query historical and public documents known as records at TNA.
+
+For help setting up a development environment, [view the README](https://github.com/nationalarchives/ds-search/blob/main/README.md).
+
+## Updating this documentation
+
+The navigation for this this documentation is configured in [``mkdocs.yml``](https://github.com/nationalarchives/ds-search/blob/main/mkdocs.yml). You can add new markdown files there to get them to appear in the navigation.
+
+Add/Update documentation where relevant in `docs/` folder.
+
+**IMPORTANT**: Remember that this documentation is public. Treat any sensitive data or credentials with the same level of caution that you would on any public forum.

mkdocs.yml

@@ -1,3 +1,19 @@
 site_name: DS Search Docs
 repo_url: https://github.com/nationalarchives/ds-search
 dev_addr: 0.0.0.0:65532
+theme:
+  name: material
+  font: false
+markdown_extensions:
+  - sane_lists
+  - toc:
+      permalink: true
+nav:
+  - 'Home': 'index.md'
+  - 'Developer guide':
+      - 'Project conventions': 'developer-guide/project-conventions.md'
+      - 'Contributing code': 'developer-guide/contributing.md'
+      - 'Dependency management': 'developer-guide/dependency-management.md'
+      - 'Local development gotchas': 'developer-guide/local-development-gotchas.md'
+      - 'Backend development': 'developer-guide/backend.md'
+      - 'Frontend development': 'developer-guide/frontend.md'