Skip to content

Latest commit

 

History

History
185 lines (120 loc) · 5.1 KB

CONTRIBUTE.md

File metadata and controls

185 lines (120 loc) · 5.1 KB

Contribute

Contributions are very welcome!

We're also open to allow co-maintainers.

What to contribute?

Read into the Troubleshooting Guide to get some insight on how the stack works.

Know How

  • Do not commit database migrations - they will be created on release.
  • As we mainly use SQLite as database we should keep the DB writes to a minimum, so we do not run into locking issues (OperationalError: database is locked)
  • Important fixes and features should be added to the CHANGELOG.md file
  • This project is API-first - the API should be built for clean external usage.
  • Add new views, APIs and job-execution-features to the integration tests (test/integration/)

Install

Directly

# download
git clone https://github.com/O-X-L/ansible-webui

# install dependencies (venv recommended)
cd webui
python3 -m pip install --upgrade -r requirements.txt
bash scripts/update_version.sh
export AW_VERSION="$(cat VERSION)"

# run
python3 src/oxl_ansible_webui/

Frontend

You need to have Node.js installed.

Quick install: bash ./scripts/frontend/nodejs_install.sh

Using Docker

docker image pull oxlorg/ansible-webui:dev
cd ${PATH_TO_SRC}  # repository root directory
docker run -it --name ansible-webui-dev --publish 127.0.0.1:8000:8000 --volume /tmp/awtest:/data --volume $(pwd):/aw oxlorg/ansible-webui:dev

Frontend

todo..

Development

You can run the service in its development mode:

bash ${REPO}/scripts/run_dev.sh

Run in staging mode: (close to production behavior)

bash ${REPO}/scripts/run_staging.sh

Admin user for testing:

  • User: ansible
  • Pwd: automateMe

Frontend

To build the frontend bundles - you can either run:

  • bash ./scripts/run_dev.sh for the full app
  • bash ./scripts/frontend/run_updater.sh for automatic update whenever code changes
  • bash ./scripts/frontend/build.sh to build it once

The bundles are generated into src/oxl_ansible_webui/aw/static_dev - django will use this statics-directory in dev-mode.

DO NOT copy & commit bundles to/in src/oxl_ansible_webui/aw/static - they are only generated/updated on release.

This is also necessary if a sub-component is used in multiple others. You will see a 404 error if the js-files are missing from the script. (as they are not copied to django's static-dir)

When adding additional svelte-apps - they should be added to script/frontend/validate_prod_build.sh.

Translations

Translations are added in src/oxl_ansible_webui/aw/config/language.py.

New languages also have to be added to the frontend in frontend/src/base/Nav.svelte and the country's flag needs to be added to src/oxl_ansible_webui/aw/static/img/.

Testing

Test to build the app using PIP:

bash ${REPO}/scripts/run_pip_build.sh

Run tests and lint:

python3 -m pip install -r ${REPO}/requirements.txt
python3 -m pip install -r ${REPO}/requirements_lint.txt
python3 -m pip install -r ${REPO}/requirements_test_backend.txt
python3 -m pip install -r ${REPO}/requirements_test_frontend.txt

bash ${REPO}/scripts/lint.sh
bash ${REPO}/scripts/test.sh

API

Many-to-Many relations

DRF serializing is a little harder for many-to-many relations.

To make it work:

  1. Initialize the choices for correct validation - example:
class BaseAlertWriteRequest(serializers.ModelSerializer):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields['jobs'] = serializers.MultipleChoiceField(choices=[job.id for job in Job.objects.all()])

    jobs = serializers.MultipleChoiceField(allow_blank=True, choices=[])
  1. The update of the FK has to be done manually - example:
def update_jobs(alert: BaseAlert, job_ids: list):
    jobs = []
    for job_id in job_ids:
        try:
            jobs.append(Job.objects.get(id=job_id))
  
        except ObjectDoesNotExist:
            continue
  
    alert.jobs.set(jobs)
 
 update_jobs(alert=alert, job_ids=serializer.validated_data.pop('jobs'))
 AlertGlobal.objects.filter(id=alert.id).update(**serializer.validated_data)

Unique constraints

DRF has some issues with validating UC's set at model level.

To work around this - we can disable this validation:

class RepositoryWriteRequest(serializers.ModelSerializer):
    class Meta:
        model = Repository
        fields = Repository.api_fields_write

    name = serializers.CharField(validators=[])  # uc on update