Skip to content

Latest commit

 

History

History
129 lines (78 loc) · 5.43 KB

CONTRIBUTING.md

File metadata and controls

129 lines (78 loc) · 5.43 KB
Raw

Development

Prerequisites

Contributions of wissen-digital-ewb

Workflow

The development of a feature for this repository is inspired from the workflow described by Vincent Driessen:

  1. Create an issue on the github repository

    Discussion about the implementation details should occur within this issue.

  2. Checkout main and pull the latest changes

    git checkout develop
    git pull

  3. Create a branch from develop to work on your issue (see below, the "Branch name convention" section)

    git checkout -b feature-myfeature

    We have agreed to use only branch names that have a - instead of / between words.

  4. Push your local branch on the remote server origin

    git push

    If your branch does not exist on the remote server yet, git will provide you with instructions, simply follow them

  5. Submit a pull request (PR)

    • Follow the steps of the github help to create the PR.
    • Please note that you PR should be directed from your branch (for example myfeature) towards the branch main

  6. Describe briefly (i.e. in one or two lines) what you changed in the CHANGELOG.md file. End the description by the number in parenthesis (#<your PR number>)

  7. Commit the changes to the CHANGELOG.md file

  8. Write the PR number in the corresponding issue so that they are linked. Write it with one of the special keywords so that the issue will be automatically closed when the PR is merged (example: Closes #<your issue number>)

  9. Ask for review of your PR

  10. Check that, after this whole process, you branch does not have conflict with main (github prevents you to merge if there are conflicts). In case of conflicts you are responsible to fix them on your branch before your merge (see below "Fixing merge conflicts" section)

  11. (if approved) Merge the PR into main and delete the branch on which you were working. In the merge message on github, you can notify people who are currently working on other branches that you just merged into main, so they know they have to check for potential conflicts with main

Fixing merge conflicts

Avoid large merge conflict by merging the updated main versions in your branch.

In case of conflicts between your branch and main you must solve them locally.

  1. Get the latest version of main

    git checkout main
    git pull

  2. Switch to your branch

    git checkout <your branch>

  3. Merge main into your branch

    git merge main

  4. The conflicts have to be manually resolved

Branch name convention

The convention is to always have feature/ in the branch name. The myfeature part should describe shortly what the feature is about (separate words with _).

Try to follow these conventions for commit messages:

  • Keep the subject line short (i.e. do not commit more than a few changes at the time)
  • Use imperative for commit messages
  • Do not end the commit message with a period You can use
git commit --amend

to edit the commit message of your latest commit (provided it is not already pushed on the remote server). With --amend you can even add/modify changes to the commit.

Project structure

The wissen-digital-ewb plattform is build upon the Django Webframework to implement the interaction between the data its database (e.g. factsheets etc) and their representation in the web frontend:

[here goes the image]

Models

Models are python structures used by django that represent tables and relations inside the django database. Please refer to the Django documentation for further information.

URL Dispatcher

Whenever users connects to the OEP (via web interface or API) they do so via an url. These urls are processed by URL Dispatchers that parse its internal structure and call the corresponding View

Views

Views are python methods that collect all data that is needed to answer the user's request or show the requested page. You may use the django models to load data from the django database or SQLAlchemy to access data in the primary database. Please refer to the Django documentation for further information.

Templates

Django is using Jinja2-templates that take data submitted by a view and renders it into an html form. The design is based on a variety of templates that should be inherited by every new template. Please choose the most specific template to modify in case of extending or modifying the design.