From f992331bf44bae319d5bade7c7f0badf4f356cce Mon Sep 17 00:00:00 2001 From: Nathan Sprenkle Date: Tue, 9 May 2023 14:30:31 -0400 Subject: [PATCH] docs: maintainership prep (#178) * docs: add codeowners file * docs: add catalog-info.yaml * docs: update README * docs: add deploy information * docs: update contributing info --- README.rst | 202 ++++++++++++++++++++++++++++++++++++++++++++++ catalog-info.yaml | 22 +++++ 2 files changed, 224 insertions(+) create mode 100644 README.rst create mode 100644 catalog-info.yaml diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..f142282 --- /dev/null +++ b/README.rst @@ -0,0 +1,202 @@ +frontend-app-ora-grading +######################## + +|ci-badge| |codecov-badge| |doc-badge| |license-badge| |status-badge| + +Purpose +******* + +The ORA Staff Grading App is a micro-frontend (MFE) staff grading experience +for Open Response Assessments (ORAs). This experience was designed to +streamline the grading process and enable richer previews of submission content +and, eventually, replace on-platform grading workflows for ORA. + +When enabled, ORAs with a staff grading step will link to this new MFE when +clicking "Grade Available Responses" from the ORA or link in the instructor +dashboard. + +The ORA Staff Grader depends on the `lms/djangoapps/ora_staff_grader +` +app in ``edx-platform``. + +Getting Started +*************** + +Developing +========== + +One Time Setup +-------------- + +First, clone the repo, install code prerequisites, and start the app. + +.. code-block:: + + # Clone the repository + git clone git@github.com:openedx/frontend-app-ora-grading.git + cd frontend-app-ora-grading + + # Install prerequisites + npm install + + # Start the MFE + npm run start + +The app will, by default, run on `http://localhost:1993` unless otherwise +specified in ``.env.development:PORT`` and ``.env.development:BASE_URL``. + +Next, enable the ORA Grading micro-frontend in `edx-platform` + +#. Add the path to the ORA Grading app in `edx-platform`: + + #. Go to your environment settings (e.g. `edx-platform/lms/envs/private.py`) + + #. Add the environment variable, ``ORA_GRADING_MICROFRONTEND_URL`` pointing + to the ORA Grading app location (e.g. ``http://localhost:1993``). + +#. Start / restart the ``edx-platform`` ``lms``. + +#. Enable the ORA Grading feature in Django Admin. + + #. Go to Django Admin (`{lms-root}/admin`) + + #. Navigate to ``django-waffle`` > ``Flags`` and click ``add/enable a new + flag``. + + #. Add a new flag called ``openresponseassessment.enhanced_staff_grader`` + and enable it. + +From there, visit an Open Response Assessment with a Staff Graded Step and +click the "View and grade responses" button to begin grading in the ORA Staff +Grader experience. + + +Making Changes +-------------- + +Get / install the latest code: + +.. code-block:: + + # Grab the latest code + git checkout master + git pull + + # Install/update the dev requirements + npm install + + +Before committing: + +.. code-block:: + + # Make a new branch for your changes + git checkout -b / + + # Using your favorite editor, edit the code to make your change. + + # Run your new tests + npm test + + # Commit all your changes + git commit ... + git push + + # Open a PR and ask for review. + +Deploying +========= + +This component follows the standard deploy process for MFEs. For details, see +the `MFE production deployment guide`_ + +.. _MFE production deployment guide: https://openedx.github.io/frontend-platform/#production-deployment-strategy + +Getting Help +************ + +Documentation +============= + +See `ORA Staff Grading on ReadTheDocs`_ for more in-depth usage information. + +.. _ORA Staff Grading on ReadTheDocs: https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/ORA_Staff_Grading.html#ora-staff-grading + +More Help +========= + +If you're having trouble, we have discussion forums at +https://discuss.openedx.org where you can connect with others in the community. + +Our real-time conversations are on Slack. You can request a `Slack +invitation`_, then join our `community Slack workspace`_. + +For anything non-trivial, the best path is to open an issue in this repository +with as many details about the issue you are facing as you can provide. + +https://github.com/openedx/frontend-app-ora-grading/issues + +For more information about these options, see the `Getting Help`_ page. + +.. _Slack invitation: https://openedx.org/slack +.. _community Slack workspace: https://openedx.slack.com/ +.. _Getting Help: https://openedx.org/getting-help + +License +******* + +The code in this repository is licensed under the GNU Affero General Public +License v3.0 unless otherwise noted. + +Please see `LICENSE `_ for details. + +Contributing +************ + +This project is currently only accepting bug fixes, security fixes, and +maintenance work. New features should be discussed in advance with the owning +team and added to the public roadmap or they may not be accepted. You can start +a conversation by creating a new issue on this repo summarizing your feature +idea. + +Please read `How To Contribute `_ for +details. + +The Open edX Code of Conduct +**************************** + +All community members are expected to follow the `Open edX Code of Conduct`_. + +.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/ + +People +****** + +The assigned maintainers for this component and other project details may be +found in `Backstage`_. Backstage pulls this data from the ``catalog-info.yaml`` +file in this repo. + +.. _Backstage: https://open-edx-backstage.herokuapp.com/catalog/default/component/frontend-app-ora-grading + +Reporting Security Issues +************************* + +Please do not report security issues in public. Please email security@tcril.org. + +.. |ci-badge| image:: https://github.com/openedx/frontend-app-ora-grading/actions/workflows/ci.yml/badge.svg + :target: https://github.com/openedx/frontend-app-ora-grading/actions/workflows/ci.yml + :alt: CI + +.. |codecov-badge| image:: https://codecov.io/github/openedx/frontend-app-ora-grading/coverage.svg?branch=master + :target: https://codecov.io/github/openedx/frontend-app-ora-grading?branch=master + :alt: Codecov + +.. |doc-badge| image:: https://readthedocs.org/projects/frontend-app-ora-grading/badge/?version=latest + :target: https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/ORA_Staff_Grading.html + :alt: Documentation + +.. |license-badge| image:: https://img.shields.io/github/license/openedx/frontend-app-ora-grading.svg + :target: https://github.com/openedx/frontend-app-ora-grading/blob/master/LICENSE + :alt: License + +.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen diff --git a/catalog-info.yaml b/catalog-info.yaml new file mode 100644 index 0000000..cff583e --- /dev/null +++ b/catalog-info.yaml @@ -0,0 +1,22 @@ +# This file records information about this repo. Its use is described in OEP-55: +# https://open-edx-proposals.readthedocs.io/en/latest/processes/oep-0055-proc-project-maintainers.html + +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: 'frontend-app-ora-grading' + description: "Frontend grading experience for Open Response Assessments (ORAs)" + links: + - url: "ora-grading.edx.org" + title: "Production Site" + icon: "Web" + - url: "ora-grading.stage.edx.org" + title: "Stage Site" + icon: "Web" +spec: + owner: group:content-aurora + type: 'website' + lifecycle: 'production' + dependsOn: + - 'edx-ora2' + - 'edx-platform'