Skip to content

Latest commit

 

History

History
194 lines (141 loc) · 8.65 KB

CONTRIBUTING.md

File metadata and controls

194 lines (141 loc) · 8.65 KB
Raw

Back to README

Contributing

MyLA is fully open source and being actively developed by Information and Technology Services, University of Michigan and Centre for Teaching, Learning and Technology, University of British Columbia. The backend is written in Python using the Django framework, and the frontend is written in JavaScript using React. We welcome any kind of contribution, from code to improvements in documentation and suggestions for future development.

Technology Overview

Frontend

The frontend of MyLA is written in JavaScript using React, with Material-UI as the component library and D3 for the data visualizations.

The code for the frontend is located under /assets/src/. MyLA uses functional components instead of class-based components and uses React hooks for state and side-effects. Jest is used as the testing framework; see Testing for more information.

Standard is the JavaScript linter. Please ensure any new code is Standard-complaint by running the linter manually. It is installed as a dev dependency. There are also text editor plugins available.

npm install
npx standard assets/src

Backend

The MyLA backend is build using the Django framework and uses MySQL for a database platform.

MyLA can only be run in production as an LTI tool. Previous versions of MyLA supported SAML, but this has been removed with a preference on launching via LTI Advantage.

Included in the source code is a cron job (dashboard/cron.py) that is used for populating the Canvas context and event data in the MySQL database. Each institution may need to configure various settings differently based on their infrastructure. More info on various institutions' infrastructure set-up is here.

Create an issue

Before sending a pull request, please create an issue describing either a problem (i.e. bug) in MyLA or a feature (i.e. enhancement) to be contributed. We will do our best to review the issue in a timely manner to discuss before starting work to address the issue.

Creating pull requests

Once the issue has been discussed with one of the project maintainers, please follow these steps for creating a pull request.

  1. Fork this project on GitHub by pressing the "Fork" button in the top-right hand corner of the repository's home page.

  2. Clone the forked repository to the local machine.

    git clone https://github.com/{github-username}/my-learning-analytics.git

  3. Add an upstream remote to the main project repository.

    git remote add upstream https://github.com/tl-its-umich-edu/my-learning-analytics.git

  4. Create local branches to keep contributions organized (generally one branch for each issue).

    git checkout -b issue-xxx-fix-a-bug

  5. Make changes and push to your fork (origin remote).

    git add .
git commit -m 'Make some changes'
git push origin issue-xxx-fix-a-bug

  6. Once changes have been pushed to the branch on your fork, GitHub will show a button to create a pull request from the forked repository to the main project repository. Click this and provide details about the changes in the description, making sure to mention (using #) the issue you want to resolve. Whenever possible, include a test plan with steps to aid reviewers.

  7. When your PR is merged (or when others are), pull from upstream to keep your local master branch up to date.

    git checkout master
git pull upstream master

Code review

All contributions must be code reviewed. Contributions may need to be changed before they can be accepted. We really appreciate tests as well, so if at all possible please try to add them.

Tips for working with Git

When working with branches, we recommend using the options git config --global branch.autosetuprebase always and git config --global pull.rebase true. It will make it so you always use the --rebase flag when pulling changes from master. This avoids unintentional merge commits, keeps the local branch clean, and makes it easier to rebase the branch in the future. These options can be changed at any time if they aren't working well for the situation.

Another great option that will save some time is git config --global push.default current. This helps you avoid having to set an upstream everytime and makes it easier to run git push.

Reference these GitHub guides on Forking Projects and Understanding the GitHub flow for further information.

Development tips

  1. Connect to the Docker container, and edit some files!

    docker exec -it student_dashboard /bin/bash`
# Then install a text editor like vim
apt-get -y install vim

    Then files may be edited. (Most code is in/code/dashboard.)

  2. Restart gunicorn to re-read the configuration. This is useful to avoid a redeploy.

    docker exec student_dashboard pkill -HUP gunicorn

  3. VS Code debugging within Docker containers is supported via DEBUGPY (formerly PTVSD). See the VS Code docs for details.

    A few variables may be defined in the env.hjson file to configure this, but minimally DEBUGPY_ENABLE must be set to true. Currently docker-compose.yml opens two ports that can be used currently, 3000 and 3001. More may be opened, if needed. These can be configured with other variables. See env_sample.hjson for more details.

    When debugging the cron job, you'll need to use a different approach with a different port and settings. First, start the container as normal with DEBUGPY_ENABLE set to false in env.hjson. Then, issue the below command, which enters the container, sets some environment variables, then runs the cron. The job will start running when the debugger is attached in VS Code.

    docker exec -it student_dashboard /bin/bash \
    -c "DEBUGPY_WAIT_FOR_ATTACH=True DEBUGPY_ENABLE=TRUE DEBUGPY_REMOTE_PORT=3001 \
    ./manage_debugpy.py runcrons --force"

Database Upgrade in Development

While working on issues, MyLA's docker-compose.yml may need to be updated to use a newer version of MySQL. Some new versions may cause MySQL to complain about using an older DB.

For example, MySQL's log may contain warnings like:

InnoDB: Table mysql/innodb_table_stats has length mismatch in the column name table_name.  Please run mysql_upgrade

This problem can be resolved by running the recommended upgrade in the MySQL container:

docker exec -it student_dashboard_mysql mysql_upgrade \
    --user=root --password student_dashboard

When prompted, specify the password for the root MySQL user. It should be found in the MYSQL.ROOT_PASSWORD property of env.hjson.

Backing up the development database

To backup the development databaes with the default settings, use this command

docker exec student_dashboard_mysql mysqldump --socket=/tmp/mysql.sock -uroot -pstudent_dashboard_root_pw student_dashboard > student_dashboard.sql

To restore this database to a new database you had created as an admin called student_dashboard_new (CREATE database student_dashboard_new). You can also just restore it to the same database (student_dashboard).

docker exec -i student_dashboard_mysql mysql -uroot -pstudent_dashboard_root_pw student_dashboard < student_dashboard.sql

Note: It's possible you may need to recreate the database (delete the .data directory) if your value in docker-compose was MYSQL_ROOT_HOST="0.0.0.0" which makes it difficult to connect to MySQL.

Dependency Upgrade

For Auto-upgrade django to future version, use the helpful library called django-upgrade

Next: Contributors