Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (50 loc) · 6.23 KB

CONTRIBUTING.md

File metadata and controls

80 lines (50 loc) · 6.23 KB
Raw

How to Contribute To My Learning Analytics

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 back-end is written in Python using the Django framework, and the front-end is written in JavaScript using React. We welcome any kind of contribution, from code to improvements in documentation to suggestions for future development.

Technology Overview

Front-end

The front end of MyLA is written in JavaScript using React, with Material-UI as the component library and D3 for the data visualizations. Jest is used as the testing framework - more information can be found below for running the tests.

The code for the front-end is located under /assets/src/. MyLA uses functional components instead of class-based components and uses React hooks for state and side-effects.

Standard is the JavaScript linter. Please ensure that your code is Standard-complaint by running the linter manually. It is installed as a dev-dependency and you should be able to run it by simply typing standard.

Back-end

MyLA Backend is build using Django Framework, MySQL DataBase, Cron schedule for getting the Canvas context and event data to the MySQL DB each institution might set this up differently based on the infrastruture support. MyLA can be run as a stand alone tool with SAML support and as LTI tool.

More info of 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 you would like to contribute. We'll do our best to review the issue in a timely manner to discuss before starting work to address the issue.

Tips for working with Git

When working with branches it's advisable to use the options git config --global branch.autosetuprebase always and git config --global pull.rebase true

To always do a git pull --rebase when merging back changes from master. This avoids unintentional merge commits, keeps your branch clean and makes it easier to rebase your branch in the future. These options can be changed at any time if you find they aren't working well for you.

Another great option that will save you some time is git config --global push.default current

This avoids you having to set an upstream everytime and just lets you run git push

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

Making a pull request

Once you have had a chance to discuss the issue with one of the project maintainers, please follow these steps for making a pull request.

  1. Fork this project on Github by pressing the Fork button on the top-right hand corner.
  2. Clone the forked repository to your local machine. git clone https://github.com/{github-username}/my-learning-analytics.git.
  3. Try to create local branches to keep your contributions organized - generally one branch for each issue.
  4. Once you've pushed your changes to your fork, you should see a button on Github to create a pull request from your forked repository to the main project repository.

Testing tips!

  1. Connect to the docker and edit some files!

    docker exec -it student_dashboard /bin/bash

    then install a text editor like vim apt-get -y install vim

Then you can edit your files! (Probably in /code/dashboard)

  1. Restart the gunicorn to read the configuration. This is useful to avoid a redeploy.

    docker exec student_dashboard pkill -HUP gunicorn

  2. The django-debug-toolbar is available for debugging. For this to be displayed.

  1. VsCode is supported via PTVSD for debugging the code running in Docker. See this information here for details https://code.visualstudio.com/docs/python/debugging#_remote-debugging

    A few variables are available to be defined in the .env file to enable this but minimally you have to set PTVSD_ENABLE=True. Currently docker-compose.yml opens 2 ports that can be used current, 3000 and 3001. If you need more you can open them. You can configure these with other variables. See the .env.sample for examples.

    If you want to connect to the cron job you'll have to use a different port as Django uses 3000 by default and also wait for attach.

    Set your breakpoints then run this command in the docker instance! Then connect to the cron configuration. The job will start when you attach the debugger. docker exec -it student_dashboard /bin/bash -c "PTVSD_WAIT_FOR_ATTACH=True PTVSD_ENABLE=TRUE PTVSD_REMOTE_PORT=3001 ./manage_ptvsd.py runcrons --force"

Running front-end tests

docker exec -it webpack_watcher npm test will run the test suite for the front-end React application. Jest is the testing framework used. More tests (including back-end tests) are planned for the future.

Code Review

All contributions will be code reviewed and you may need to make some changes to your contribution. We really appreciate tests as well, so if at all possible please try to add tests.