From 70e13eccfa19d79598054e54d21833587169c7f7 Mon Sep 17 00:00:00 2001 From: Jhon Vente <134975835+johnvente@users.noreply.github.com> Date: Tue, 12 Sep 2023 12:01:10 -0500 Subject: [PATCH] [DOCS] Readme updated according OEP-55 (#194) * docs: README updated * docs: update some badges and content * fix: getting help url --------- Co-authored-by: Edward Zarecor Co-authored-by: Matthew Carter --- README.rst | 115 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 73 insertions(+), 42 deletions(-) diff --git a/README.rst b/README.rst index 878d5ce0..67ac3172 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,8 @@ frontend-app-ora-grading -######################## +############################# + +|license-badge| |status-badge| |ci-badge| |codecov-badge| -|ci-badge| |codecov-badge| |doc-badge| |license-badge| |status-badge| Purpose ******* @@ -22,25 +23,56 @@ app in ``edx-platform``. Getting Started *************** +Prerequisites +============= + +The `devstack`_ is currently recommended as a development environment for your +new MFE. If you start it with ``make dev.up.lms`` that should give you +everything you need as a companion to this frontend. + +Note that it is also possible to use `Tutor`_ to develop an MFE. You can refer +to the `relevant tutor-mfe documentation`_ to get started using it. + +.. _Devstack: https://github.com/openedx/devstack + +.. _Tutor: https://github.com/overhangio/tutor + +.. _relevant tutor-mfe documentation: https://github.com/overhangio/tutor-mfe#mfe-development + Developing ========== -One Time Setup +Cloning and Startup -------------- 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 + 1. Clone your new repo: + + ``git clone git@github.com:openedx/frontend-app-ora-grading.git`` - # Start the MFE - npm run start + 2. Use node v18.x. + + The current version of the micro-frontend build scripts support node 18. + Using other major versions of node *may* work, but this is unsupported. For + convenience, this repository includes an .nvmrc file to help in setting the + correct node version via `nvm `_. + + 3. Install npm dependencies: + + ``cd frontend-app-ora-grading && npm install`` + + 4. Update the application port to use for local development: + + Default port is 1993. If this does not work for you, update the line + `PORT=1993` to your port in all .env.* files + + 5. Start the dev server: + + ``npm start`` The app will, by default, run on `http://localhost:1993` unless otherwise specified in ``.env.development:PORT`` and ``.env.development:BASE_URL``. @@ -112,24 +144,24 @@ the `MFE production deployment guide`_ .. _MFE production deployment guide: https://openedx.github.io/frontend-platform/#production-deployment-strategy -Getting Help -************ - -Documentation -============= +Internationalization +==================== -See `ORA Staff Grading on ReadTheDocs`_ for more in-depth usage information. +Please see refer to the `frontend-platform i18n howto`_ for documentation on +internationalization. -.. _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 +.. _frontend-platform i18n howto: https://github.com/openedx/frontend-platform/blob/master/docs/how_tos/i18n.rst -More Help -========= +Getting 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`_. +invitation`_, then join our `community Slack workspace`_. Because this is a +frontend repository, the best place to discuss it would be in the `#wg-frontend +channel`_. 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. @@ -140,27 +172,30 @@ 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 +.. _#wg-frontend channel: https://openedx.slack.com/archives/C04BM6YC7A6 +.. _Getting Help: https://openedx.org/community/connect License ******* -The code in this repository is licensed under the GNU Affero General Public -License v3.0 unless otherwise noted. +The code in this repository is licensed under the AGPLv3 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. +Contributions are very welcome. Please read `How To Contribute`_ for details. -Please read `How To Contribute `_ for -details. +.. _How To Contribute: https://openedx.org/r/how-to-contribute + +This project is currently accepting all types of contributions, bug fixes, +security fixes, maintenance work, or new features. However, please make sure +to have a discussion about your new feature idea with the maintainers prior to +beginning development to maximize the chances of your change being accepted. +You can start a conversation by creating a new issue on this repo summarizing +your idea. The Open edX Code of Conduct **************************** @@ -181,22 +216,18 @@ file in this repo. Reporting Security Issues ************************* -Please do not report security issues in public. Please email security@openedx.org. +Please do not report security issues in public, and email security@openedx.org instead. + +.. |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 .. |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 + :alt: Continuous Integration .. |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