Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
178 lines (131 loc) · 7.84 KB

CONTRIBUTING.md

File metadata and controls

178 lines (131 loc) · 7.84 KB

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.

Next: Contributors

Dependency Upgrade

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