From 644451cab88fa0b7131cffa01ed1db50bf3d1191 Mon Sep 17 00:00:00 2001 From: johnvente Date: Wed, 28 Jun 2023 13:57:19 -0500 Subject: [PATCH 1/4] docs: Udate readme with frontend-template-application readme template --- README.rst | 178 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 155 insertions(+), 23 deletions(-) diff --git a/README.rst b/README.rst index 0b2fcbc708..b482360376 100644 --- a/README.rst +++ b/README.rst @@ -1,18 +1,78 @@ -|Build Status| |Codecov| |license| - -############################# frontend-app-course-authoring ############################# -Please tag `@edx/teaching-and-learning `_ on any PRs or issues. Thanks. +|license-badge| |status-badge| |ci-badge| |codecov-badge| + + +Purpose +******* + +This repository is a template for Open edX micro-frontend applications. It is +flagged as a Template Repository, meaning it can be used as a basis for new +GitHub repositories by clicking the green "Use this template" button above. +The rest of this document describes how to work with your new micro-frontend +**after you've created a new repository from the template.** ************ -Introduction +Getting Started ************ -This is the Course Authoring micro-frontend, currently under development by `2U `_. +After copying the template repository, you'll want to do a find-and-replace to +replace all instances of ``frontend-template-application`` with the name of +your new repository. Also edit index.html to replace "Application Template" +with a friendly name for this application that users will see in their browser +tab. + +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 + +Cloning and Startup +=================== + +In the following steps, replace "[PLACEHOLDER]" with the name of the repo you +created when copying this template above. + + +1. Clone your new repo: + + ``git clone https://github.com/openedx/frontend-app-course-authoring.git`` + +2. Use node v18.x. -Its purpose is to provide both a framework and UI for new or replacement React-based authoring features outside ``edx-platform``. You can find the current set described below. + 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-course-authoring && npm install`` + +4. Update the application port to use for local development: + + Default port is 2001. If this does not work for you, update the line + `PORT=2001` to your port in all .env.* files + +5. Start the dev server: + + ``npm start`` + + +The dev server is running at `http://localhost:2001 `_. +or whatever port you setup. ******** Features @@ -151,22 +211,6 @@ Developing `Devstack `_. If you start Devstack with ``make dev.up.studio`` that should give you everything you need as a companion to this frontend. -Installation and Startup -======================== - -1. Clone the repo: - - ``git clone https://github.com/openedx/frontend-app-course-authoring.git`` - -2. Install npm dependencies: - - ``cd frontend-app-course-authoring && npm install`` - -3. Start the dev server: - - ``npm start`` - -The dev server is running at `http://localhost:2001 `_. If your devstack includes the default Demo course, you can visit the following URLs to see content: @@ -197,3 +241,91 @@ The production build is created with ``npm run build``. :target: https://codecov.io/gh/edx/frontend-app-course-authoring .. |license| image:: https://img.shields.io/npm/l/@edx/frontend-app-course-authoring.svg :target: @edx/frontend-app-course-authoring + +Internationalization +==================== + +Please see refer to the `frontend-platform i18n howto`_ for documentation on +internationalization. + +.. _frontend-platform i18n howto: https://github.com/openedx/frontend-platform/blob/master/docs/how_tos/i18n.rst + +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`_. 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. + +https://github.com/openedx/frontend-template-application/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/ +.. _#wg-frontend channel: https://openedx.slack.com/archives/C04BM6YC7A6 +.. _Getting Help: https://openedx.org/getting-help + +License +******* + +The code in this repository is licensed under the AGPLv3 unless otherwise +noted. + +Please see `LICENSE `_ for details. + +Contributing +************ + +Contributions are very welcome. 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 +**************************** + +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-template-application + +Reporting Security Issues +************************* + +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-template-application.svg + :target: https://github.com/openedx/frontend-template-application/blob/main/LICENSE + :alt: License + +.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen + +.. |ci-badge| image:: https://github.com/openedx/frontend-template-application/actions/workflows/ci.yml/badge.svg + :target: https://github.com/openedx/frontend-template-application/actions/workflows/ci.yml + :alt: Continuous Integration + +.. |codecov-badge| image:: https://codecov.io/github/openedx/frontend-template-application/coverage.svg?branch=main + :target: https://codecov.io/github/openedx/frontend-template-application?branch=main + :alt: Codecov \ No newline at end of file From c2933766a5963542a6a58ad2680b29b0ed30c86c Mon Sep 17 00:00:00 2001 From: johnvente Date: Wed, 28 Jun 2023 22:30:22 -0500 Subject: [PATCH 2/4] docs: update ci badge and porpuse --- README.rst | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/README.rst b/README.rst index b482360376..210bf35fb8 100644 --- a/README.rst +++ b/README.rst @@ -1,17 +1,16 @@ frontend-app-course-authoring ############################# -|license-badge| |status-badge| |ci-badge| |codecov-badge| +|license-badge| |status-badge| |codecov-badge| Purpose ******* -This repository is a template for Open edX micro-frontend applications. It is -flagged as a Template Repository, meaning it can be used as a basis for new -GitHub repositories by clicking the green "Use this template" button above. -The rest of this document describes how to work with your new micro-frontend -**after you've created a new repository from the template.** +This is the Course Authoring micro-frontend, currently under development by `2U `_. + +Its purpose is to provide both a framework and UI for new or replacement React-based authoring features outside ``edx-platform``. You can find the current set described below. + ************ Getting Started @@ -309,23 +308,19 @@ 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-template-application +.. _Backstage: https://open-edx-backstage.herokuapp.com/catalog/default/component/frontend-app-course-authoring Reporting Security Issues ************************* 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-template-application.svg - :target: https://github.com/openedx/frontend-template-application/blob/main/LICENSE +.. |license-badge| image:: https://img.shields.io/github/license/openedx/frontend-app-course-authoring.svg + :target: https://github.com/openedx/frontend-app-course-authoring/blob/master/LICENSE :alt: License .. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen -.. |ci-badge| image:: https://github.com/openedx/frontend-template-application/actions/workflows/ci.yml/badge.svg - :target: https://github.com/openedx/frontend-template-application/actions/workflows/ci.yml - :alt: Continuous Integration - -.. |codecov-badge| image:: https://codecov.io/github/openedx/frontend-template-application/coverage.svg?branch=main - :target: https://codecov.io/github/openedx/frontend-template-application?branch=main +.. |codecov-badge| image:: https://codecov.io/github/openedx/frontend-app-course-authoring/coverage.svg?branch=master + :target: https://codecov.io/github/openedx/frontend-app-course-authoring?branch=master :alt: Codecov \ No newline at end of file From 2740c8563ccfd70e57f5e104a1c6c373bd03911c Mon Sep 17 00:00:00 2001 From: johnvente Date: Mon, 10 Jul 2023 07:25:01 -0500 Subject: [PATCH 3/4] fix: getting help and issues urls --- README.rst | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 210bf35fb8..c64891fb18 100644 --- a/README.rst +++ b/README.rst @@ -16,12 +16,6 @@ Its purpose is to provide both a framework and UI for new or replacement React-b Getting Started ************ -After copying the template repository, you'll want to do a find-and-replace to -replace all instances of ``frontend-template-application`` with the name of -your new repository. Also edit index.html to replace "Application Template" -with a friendly name for this application that users will see in their browser -tab. - Prerequisites ============= @@ -263,14 +257,14 @@ 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. -https://github.com/openedx/frontend-template-application/issues +https://github.com/openedx/frontend-app-learning/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/ .. _#wg-frontend channel: https://openedx.slack.com/archives/C04BM6YC7A6 -.. _Getting Help: https://openedx.org/getting-help +.. _Getting Help: https://openedx.org/community/connect License ******* From 3619b1e8899ba006aa1f88af1e63965359700868 Mon Sep 17 00:00:00 2001 From: Jhon Vente Date: Tue, 8 Aug 2023 23:46:16 -0500 Subject: [PATCH 4/4] docs: update readme with suggestions --- README.rst | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index c64891fb18..7b0dfcec30 100644 --- a/README.rst +++ b/README.rst @@ -35,11 +35,8 @@ to the `relevant tutor-mfe documentation`_ to get started using it. Cloning and Startup =================== -In the following steps, replace "[PLACEHOLDER]" with the name of the repo you -created when copying this template above. - -1. Clone your new repo: +1. Clone the repo: ``git clone https://github.com/openedx/frontend-app-course-authoring.git`` @@ -48,18 +45,14 @@ created when copying this template above. 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 `_. + correct node version via `nvm use`_. 3. Install npm dependencies: ``cd frontend-app-course-authoring && npm install`` -4. Update the application port to use for local development: - - Default port is 2001. If this does not work for you, update the line - `PORT=2001` to your port in all .env.* files -5. Start the dev server: +4. Start the dev server: ``npm start`` @@ -257,7 +250,7 @@ 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. -https://github.com/openedx/frontend-app-learning/issues +https://github.com/openedx/frontend-app-course-authoring/issues For more information about these options, see the `Getting Help`_ page.