Metadata-Version: 2.4
Name: devilry
Version: 6.5.2
Summary: A system for handling electronic deliveries. See https://github.com/devilry/devilry-django.
Author: Tor Johansen, Bendik Opstad, Vegard Angell, Magne Westlie, Ilya Kostolomov, Christian Tryti, Rebekka Mørken, Stian Julseth, Åsmund J. Rosendahl
Author-email: Espen Angell Kristiansen <post@appresso.no>
License: Copyright (c) 2010, Devilry contributors
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
            * Redistributions of source code must retain the above copyright
              notice, this list of conditions and the following disclaimer.
            * Redistributions in binary form must reproduce the above copyright
              notice, this list of conditions and the following disclaimer in the
              documentation and/or other materials provided with the distribution.
            * Neither the name of the Devilry contributors nor the
              names of its contributors may be used to endorse or promote products
              derived from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL COPYRIGHT OWNERS OR CONTRIBUTORS BE LIABLE FOR ANY
        DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
        ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Requires-Python: >=3.10.0
Requires-Dist: arrow<0.13.0,>=0.12.0
Requires-Dist: cradmin-legacy<7.0.0,>=6.2.0
Requires-Dist: django-allauth[socialaccount]>=0.62.0
Requires-Dist: django-crispy-forms<1.15.0,>=1.14.0
Requires-Dist: django-rq
Requires-Dist: django<5.3.0,>=5.2.3
Requires-Dist: djangorestframework
Requires-Dist: gunicorn>=23.0.0
Requires-Dist: html-sanitizer
Requires-Dist: html2text
Requires-Dist: ievv-opensource<13.0.0,>=12.0.0
Requires-Dist: markdown<3.4.0,>=3.3.0
Requires-Dist: psycopg
Requires-Dist: pycountry>=18
Requires-Dist: pygments<2.16.0,>=2.15.0
Requires-Dist: requests
Requires-Dist: urllib3>=1.26.0
Requires-Dist: whitenoise
Requires-Dist: xlsxwriter
Provides-Extra: dev
Requires-Dist: beautifulsoup4; extra == 'dev'
Requires-Dist: boto3; extra == 'dev'
Requires-Dist: dj-database-url; extra == 'dev'
Requires-Dist: django-auth-ldap; extra == 'dev'
Requires-Dist: django-silk; extra == 'dev'
Requires-Dist: django-storages; extra == 'dev'
Requires-Dist: django-types; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: htmls; extra == 'dev'
Requires-Dist: humanize; extra == 'dev'
Requires-Dist: model-bakery; extra == 'dev'
Requires-Dist: openpyxl; extra == 'dev'
Requires-Dist: pip-tools; extra == 'dev'
Requires-Dist: psutil; extra == 'dev'
Requires-Dist: pyflakes; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx; extra == 'docs'
Provides-Extra: s3storage
Requires-Dist: boto3; extra == 's3storage'
Requires-Dist: django-storages; extra == 's3storage'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: htmls; extra == 'test'
Requires-Dist: model-bakery; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-django; extra == 'test'
Requires-Dist: pytest-env; extra == 'test'
Description-Content-Type: text/markdown

# devilry

## Develop

Requires:

- https://github.com/pyenv/pyenv
- Docker (Docker desktop or similar)

### Use conventional commits for GIT commit messages

See https://www.conventionalcommits.org/en/v1.0.0/.
You can use this git commit message format in many different ways, but the easiest is:

- Use commitizen: https://commitizen-tools.github.io/commitizen/commit/
- Use an editor extension, like https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits for VScode.
- Just learn to write the format by hand (can be error prone to begin with, but it is fairly easy to learn).

### Install hatch and commitizen

NOTE: You only need hatch if you need to build releases, and you
only need commitizen for releases OR to make it easy to follow
conventional commits for your commit messages
(see _Use conventional commits for GIT commit messages_ above).

#### If using uv (recommended):
Make sure uv is installed - see https://docs.astral.sh/uv/getting-started/installation/

Then install with:

```bash
uv tool install commitizen
uv tool install hatch
```

#### If using pipx (deprecated):

```bash
brew install pipx
pipx ensurepath
pipx install hatch
pipx install commitizen
```

See https://github.com/pypa/pipx, https://hatch.pypa.io/latest/install/
and https://commitizen-tools.github.io/commitizen/ for more install alternatives if
needed, but we really recommend using pipx since that is isolated.

### Install development dependencies

#### If using uv (recommended):

```bash
uv python install 3.10
uv venv
uv pip install -e ".[dev,test,docs]"
```

#### If using pipx (deprecated):

```bash
pyenv install 3.10
pyenv local 3.10

# Create virtualenv:
./recreate-virtualenv.sh

# Install dependencies in a virtualenv:
source .venv/bin/activate   # enable virtualenv
.venv/bin/pip install -e ".[dev,test,docs]"
```


### Run postgres and redis

```bash
docker compose up
```

### Run dev server

```bash
source .venv/bin/activate   # enable virtualenv
ievv devrun
```

### Create or re-create a devdatabase
You should always clear the database before recreating it. The easiest way is just to clear the docker resources (and volumes) and start it again.
```bash
docker compose down -v
docker compose up
```

Run dev server (in a new terminal)
```bash
source .venv/bin/activate   # activate virtualenv
ievv devrun
```

Load devdatabase SQL-file (in a new terminal)
```bash
source .venv/bin/activate   # activate virtualenv
docker compose exec -T postgres psql -U dbdev --dbname=dbdev -p 5432 -h localhost < devilry/project/develop/dumps/default.sql
python manage.py migrate
ievv customsql -i -r
```

If the dump should be updated for e.g new migrations, run the following and commit to repo:
```bash
docker compose exec -T postgres pg_dump --clean --no-owner --no-acl --no-privileges -U dbdev -h localhost -p 5432 dbdev > devilry/project/develop/dumps/default.sql
```

### Test users in the devdatabase
All users have ``test`` as their password, and the most commonly needed users are:

- Superuser: grandma@example.com
- Admin (and examiner): odin@example.com
- Examiner (and student): thor@example.com
- Student: april@example.com

You can find them all by logging in as grandma@example.com and going to http://localhost.test:8000/djangoadmin/devilry_account/user/


### Browse uploaded files
Files are stored in MinIO (S3 compatible storage that is run via docker-compose).
To browse files:

- Go to http://localhost:9001/
- Login with:
  - username: ``testuser``
  - password: ``testpassword``
- Select _Object browser_ in the sidebar.

The MinIO files is stored on disk in the ``minio_devdata`` directory in the root
of the repo, and you can stop docker compose, and just run ``rm -rf minio_devdata``
to remove all the files.


### Run tests

```bash
source .venv/bin/activate   # enable virtualenv
pytest devilry
```


### Autoformat code with ruff
If you have not configured your editor to autoformat with ruff, you can run the
following command to autoformat all code in the repo:

```bash
source .venv/bin/activate   # enable virtualenvbash
ruff format .
```


### Build css/javascript:
```bash
source .venv/bin/activate   # activate virtualenv
nvm use 14    # May need to run "nvm install 14" first
ievv buildstatic
# ... or if you want to watch for changes ...:
ievv buildstatic --watch
```

To remove and reinstall all node-packages:
```bash
source .venv/bin/activate   # activate virtualenv
nvm use 14    # May need to run "nvm install 14" first
ievv buildstatic --npm-clean-node-modules
```

### Build docs
Docs are built on https://readthedocs.org/projects/devilry/ each time a branch is pushed,
but if you are making larger changes or need to debug build issues, you can build it
locally using:

```bash
sphinx-build not_for_deploy/docs/ built-docs/
```

and when the build is complete, you can open ``built-docs/index.html`` in a browser.


### Destroy postgres and redis

```bash
docker compose down -v
```

## Documentation

https://devilry.readthedocs.io

## Release

### Translations

To translate new texts, do the following:

- ``ievv makemessages``
- Translate the .po files. Poedit is a great tool for this.
- ``ievv compilemessages``
- Commit the changes


### Update docs
Create a ``not_for_deploy/docs/sysadmin/migrationguides/migrate-to-<NEWVERSION>.rst``
with update instructions for sysadmins. See the previous version for example. Skeleton:

```rst
=========================
Migrating to <NEWVERSION>
=========================

.. warning:: Always update one version at a time. Do not skip versions unless it is explicitly stated in the migration guide.


Backup database and files
#########################

BACKUP. YOUR. DATABASE. AND. FILES.


What's new?
###########

- Change 1
- Change 2


Update devilry
##############

Update the devilry version to ``<NEWVERSION>`` as described in :doc:`../update`.
```

Create a ``not_for_deploy/docs/user/changelog/<NEWVERSION>.rst`` with changelog for end-users.
This is supposed to be readable/understandable by normal users. Skeleton:

```rst
.. _<NEWVERSION>changelog:

###################################
What is new in Devilry <NEWVERSION>
###################################


Fixes
#####
- Fix 1
- Fix 2

Updates/changes
###############
- Change 1
- Change 2
```


### Set version and build staticfiles

First make sure you have NO UNCOMITTED CHANGES!

Release (create changelog, increment version, build staticfiles, commit and tag the change) with:

```bash
# Make sure you have the virtualenv active:
source .venv/bin/activate
# Make sure you are using the correct node version:
nvm use 14
# This will bump the version and then build and commit staticfiles:
tools/release/prepare-release.py prepare --apply
# Push the changes and the tags to github:
git push && git push --tags
```

To do a prerelease (RC, beta, etc.), use `--prelease` with `prepare-release.py`. The argument is just
forwarded to the `cz bump` command, so to do an RC release use:

```bash
tools/release/prepare-release.py prepare --prerelease rc --apply
```


### NOTE (release):

- `cz bump` automatically updates CHANGELOG.md, updates version file(s), commits the change and tags the release commit.
- If you are unsure about what `cz bump` will do, run it with `--dry-run`. You can use
  options to force a specific version instead of the one it automatically selects
  from the git log if needed, BUT if this is needed, it is a sign that someone has messed
  up with their conventional commits.
- `cz bump` only works if conventional commits (see section about that above) is used.
- `cz bump` can take a specific version etc, but it automatically select the correct version
  if conventional commits has been used correctly. See https://commitizen-tools.github.io/commitizen/.
- If you need to add more to CHANGELOG.md (migration guide, etc), you can just edit
  CHANGELOG.md after the release, and commit the change with a `docs: some useful message`
  commit.
- The `cz` command comes from `commitizen` (install documented above).

### What if the release fails?

See _How to revert a bump_ in the [commitizen FAQ](https://commitizen-tools.github.io/commitizen/faq/#how-to-revert-a-bump).


### Migrationguide and changelog (for official readthedocs)
- Add a migration guide to not_for_deploy/docs/sysadmin/migrationguides/
- Add a changelog to not_for_deploy/docs/user/changelog/

### Release to pypi:

```bash
hatch build -t sdist
hatch publish -u __token__
# optional cleanup:
rm dist/*
```

