Merge pull request #913 from finos/dev

Update main from dev #3

CONTRIBUTE.md

@@ -3,32 +3,47 @@ This document provides guidance for how YOU can collaborate with our project com
 
 # Accessibility Theme Builder Contribution and Governance Policies
 
-This document describes the contribution process and governance policies of the FINOS Accessibility Theme Builder project. The project is also governed by the [Linux Foundation Antitrust Policy](https://www.linuxfoundation.org/antitrust-policy/), and the FINOS [IP Policy](https://community.finos.org/assets/files/IP-Policy-9b1cd5f6c1d682e073c3c15224fc6d86.pdf), [Code of Conduct](https://community.finos.org/docs/governance/code-of-conduct), [Collaborative Principles](https://community.finos.org/docs/governance/collaborative-principles/), and [Meeting Procedures](https://community.finos.org/docs/governance/meeting-procedures/).
+This document describes the contribution process and governance policies of the FINOS Accessibility Theme Builder project. The project is also governed by the [Linux 
+Foundation Antitrust Policy](https://www.linuxfoundation.org/antitrust-policy/), and the FINOS [IP Policy](https://community.finos.org/assets/files/IP-Policy-9b1cd5f6c1d682e073c3c15224fc6d86.pdf), [Code of Conduct](https://community.finos.org/docs/governance/code-of-conduct), [Collaborative Principles](https://community.finos.org/docs/governance/collaborative-principles/), and [Meeting Procedures](https://community.finos.org/docs/governance/meeting-procedures/).
 
 ## Reporting Issues
 
 We welcome any feedback on the quality, stability or performance of Theme Builder.  If you see incorrect behavior or would like to suggest ways to improve Theme Builder, please use these guidelines to create an issue in GitHub.
 1. Please [check](https://github.com/finos/a11y-theme-builder/issues) whether there is already an open issue related to your experience/feedback. If there is, join the discussion and contribute any observations or information that may not already be present in the issue.
-2. If there isn't already a relevant issue, create one, describing your experience with Theme Builder.
+2. If there isn't already a relevant issue, create one using one of the provided templates.  Please provide the following information:
     1. Add appropriate tag for project -> [`SDK`, `theme builder app`]
         * SDK - performs calculations, creates and populates CSS variables, generates CSS and JSON output
         * theme builder app - the application that the user interacts with
     3. Add appropriate tag for type of issue -> [`bug`, `enhancement`]
     4. (optional) Add tag for required specialties -> [`design thinking`, `project management`, `question`, `documentation`]
     5. Set `Projects` field to `ThemeBuilder`
+3. If you are reporting a problem that exists in Theme Builder, try to convey answers for the following:
+    * Is the bug reproducible as explained?
+    * Is it reproducible in other environments (for instance, on different browsers or devices)?
+    * Are the steps to reproduce the bug clear? If not, can you describe how you might reproduce it?  Please provide as much relevant information as possible and break the instructions for reproducing the problem into clear, simple steps.
+    * Is this bug something you have run into?  Is it blocking you?  Would you appreciate it being looked into faster?
 4. If you would like to contribute designs, code, testing or resources toward resolving the issue, please note that in the issue.
 5. Respond to any questions or suggestions raised in the issue by other community members.
-6. We will triage all new issues at our next community meeting if you would like to offer more information as we prioritize your issue.  Click to see more [meeting information](https://github.com/finos/a11y-theme-builder/wiki/Communication#meetings).
+6. We will triage all new issues at our next community meeting if you would like to offer more information as we prioritize your issue.  Click to see more [meeting 
+information](https://github.com/finos/a11y-theme-builder/wiki/Communication#meetings).
+
+### Asking for features/enhancements
+
+Similar to reporting issues, a user wishing to create a feature request should first [check](https://github.com/finos/a11y-theme-builder/issues) whether a similar request has already been made in the system.  Searching for features should include looking for issues with the `enhancement` label.  Additionally, searching on issues with the string `[EPIC]`in the title may prove useful.
+
+If there isn't already a similar feature request, please create one using the appropriate `Feature Request Form` template.  After questions and suggestions from the community have been considered by the author and any resulting updates to the request have been made, we will triage the feature request.  If we determine the request to be sufficiently complex that we need to break work items into their own issues, the feature request will likely become an EPIC.  We will work with the author to ensure that no insights or information will be lost.
 
 ## Contribution Process
 
 Before making a contribution, please take the following steps:
 1. Check whether there's already an open issue related to your proposed contribution as described above.  If not, follow instructions above to create an issue with all relevant information.
 2. Respond to any questions or suggestions raised in the issue by other developers.
 3. Fork the project repository and prepare your proposed contribution.  All contributions should be created using the latest code from the upstream dev branch.
-    1. In commit messages, reference associated issue.  For example, `commit -m "finos/a11y-theme-builder#111: corrected button behavior"`
-    2. When your changes are ready, be sure to update your branch with the latest upstream dev branch to ensure code will merge correctly.
-    3. Retest your contribution with latest updates.
+    1. Create and checkout a new branch to make changes within: `git checkout -b "thisBranchFixesIssue#<issue no.>"`
+    2. Update your new branch with the latest upstream dev branch.
+    3. In commit messages, reference associated issue.  For example, `commit -m "finos/a11y-theme-builder#111: corrected button behavior"`
+    4. When your changes are ready, be sure to update your branch with the latest upstream dev branch to ensure code will merge correctly.
+    5. Retest your contribution with latest updates.
 4. Submit a pull request.
     * All pull requests should be made to merge into the upstream dev branch.
 
@@ -83,20 +98,13 @@ Logistics for Project Triage Sessions:
 Project Management:
 * [Project Kanban Dashboard](https://github.com/orgs/finos/projects/1/views/1)
 
-### Contributing Issue/Feature Reports
-When submitting [Issue/Feature Reports](https://github.com/finos/a11y-theme-builder/issues), please use the provided templates and try to convey answers for the following:
-
-* Is the bug reproducible as explained?
-* Is it reproducible in other environments (for instance, on different browsers or devices)?
-* Are the steps to reproduce the bug clear? If not, can you describe how you might reproduce it?
-* What tags should the bug have?
-* Is this bug something you have run into? Would you appreciate it being looked into faster?
-
 ### Contributing Code
 
 #### FINOS restrictions
 
-FINOS requires that all contributors be covered by a Contributor's License Agreement (CLA).  If you are not contributing under a current CLA, you may be an individual contributor under an Easy CLA.  For more information on contributing to this project see the [FINOS Contributor Cheatsheet](https://community.finos.org/docs/finos-contributors-cheatsheet/).  For more procedural detail on how the contribution process flows, see the [Contribution Rules](#contribution-rules) section below.
+FINOS requires that all contributors be covered by a Contributor's License Agreement (CLA).  If you are not contributing under a current CLA, you may be an individual 
+contributor under an Easy CLA.  For more information on contributing to this project see the [FINOS Contributor Cheatsheet](https://community.finos.org/docs/finos-contributors-cheatsheet/).  For more procedural detail on how the contribution process flows, see the [Contribution 
+Rules](#contribution-rules) section below.
 
 
 #### Coding Conventions
@@ -122,7 +130,8 @@ References:
 
 
 ## Testing
-Testing new releases and/or features is a great way to contribute to the community. If you find issues, please submit an [Issue/Feature Report](https://github.com/finos/a11y-theme-builder/issues).
+Testing new releases and/or features is a great way to contribute to the community. If you find issues, please submit an [Issue/Feature 
+Report](https://github.com/finos/a11y-theme-builder/issues).
 
 ## Documentation
 [Learn](./DEVELOP_DOCS.md) how to develop, build, test, and contribute to the online docs.
@@ -140,7 +149,8 @@ Our project aspires to be globally applicable but that requires internationaliza
 The project community consists of Contributors and Maintainers:
 * A **Contributor** is anyone who submits a contribution to the project. (Contributions may include code, issues, comments, documentation, media, or any combination of the above.)
 * A **Maintainer** is a Contributor who, by virtue of their contribution history, has been given write access to project repositories and may merge approved contributions.
-* The **Lead Maintainer** is the project's interface with the FINOS team and Board. They are responsible for approving [quarterly project reports](https://community.finos.org/docs/governance/#project-governing-board-reporting) and communicating on behalf of the project. The Lead Maintainer is elected by a vote of the Maintainers.
+* The **Lead Maintainer** is the project's interface with the FINOS team and Board. They are responsible for approving [quarterly project 
+reports](https://community.finos.org/docs/governance/#project-governing-board-reporting) and communicating on behalf of the project. The Lead Maintainer is elected by a vote of the Maintainers.
 
 ### Contribution Rules
 
@@ -174,3 +184,4 @@ Any Contributor who has made a substantial contribution to the project MAY apply
 
 This document MAY be amended by a vote of the Maintainers according to the Maintainer Voting process above.
 
+

DEV_GUIDE.md

@@ -6,6 +6,7 @@ This document serves as a getting started guide for working with the Accessibili
 - [Install and Use](#install-and-use)
 - [Development](#development)
 - [Understanding Server APIs](#understanding-server-apis)
+- [Creating Epics](#creating-epics)
 
 ## Install Dependencies
 The Theme Builder application can be built and run locally using two variations (Quick and Easy, Javascript Runtime Environment) that differ on complexity of setup (devops).
@@ -17,19 +18,22 @@ The Theme Builder application can be built and run locally using two variations
 ### Quick and Easy 
 If you simply desire to run the application and do not require to perform any development enhancements, the easiest approach for running the application locally is to install [Docker Desktop](https://www.docker.com/).
 ### Javascript Runtime Environment
-If you desire to extend or enhance the application, a local development environment will need to be configured. This requires the installation of Node.js prerequisites, specifically NodeJS 16+ and npm 8+. Visit [nodejs downloads](https://nodejs.org/en/download/) for latest versions.
+If you desire to extend or enhance the application, a local development environment will need to be configured. This requires the installation of Node.js prerequisites, specifically NodeJS 18+ and npm 8+. Visit [nodejs downloads](https://nodejs.org/en/download/) for latest versions.
 
 ## Install and Use
 Perform the following steps to run a local version of the application.
 
-### Fetch Latest Code
+### Fetch Latest Code from branch:dev
 These instructions assume you have a local copy of a forked instance of [finos/a11y-theme-builder](https://github.com/finos/a11y-theme-builder).
 
 ```
 cd <WORKSPACE>
 git clone https://github.com/<YOUR-ORG>/a11y-theme-builder
 cd a11y-theme-builder
+git remote add upstream https://github.com/finos/a11y-theme-builder
+git pull upstream dev
 ```
+**Note:** Always pull from the `dev` branch.  Development should always be done on the `dev` branch.
 
 where:
 
@@ -46,8 +50,27 @@ cd <WORKSPACE>/a11y-theme-builder/code
 #### Embedded Database
 The Theme Builder application requires the use of a  persisted embedded database. This requirement is satisfied by attaching a local host directory, `/code/src/data`, to the running docker container. 
 
+#### Use Docker Compose for a quick start
+Docker Compose allows you to do simple orchestration of Docker artifacts. With one command you can build and start containers and their dependencies in the proper order, establish volumes for persistence, and even establish a network so that the containers can communicate with each other. To build and start Theme Builder in a Docker environment, simply run:
+
+```
+docker compose up
+```
+
+Once the container is up and running, you may load Theme Builder in a web browser by navigating to `http://localhost:8080`.
+
+you can bring down the containers by using
+
+```
+docker compose down
+```
+
+This command gracefully shuts down the containers and cleans up the resources they used
+
 #### Build image
 
+While Docker Compose may quickly and easily start an application in a Docker environment, you may find that you need to manage your Docker environment at a more granular level. This section can help you do just that.
+
 ```
 docker build . -t a11y-theme-builder
 ``` 
@@ -164,10 +187,35 @@ Any changes made to the React source code will automatically be updated in the b
 
 Note that the build directory is not updated with these changes until an `npm run build` or `npm run build-ui` is performed.
 
-#### Potential Windows Issue
+### Potential Windows Issue
 One problem you might run into on a Windows system is that themes may not appear, load, or be created.
 If this is the case, it most likely means there is a problem with your [themes file](https://github.com/finos/a11y-theme-builder/blob/main/code/src/data/themes), which acts as the database. The most common explanation is that your environment has automatically changed the line endings of this file to `CRLF`. To fix this either use your editor to change the line endings to `LF`, or better, follow [this guide](https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings) to ensure git does not do this in the future by running the command `git config --global core.autocrlf false`, and reseting the repo.
 
+#### Our Recommendation
+We suggest you to use WSL (Windows Subsytem For Linux).`Use it from the very start of cloning the Repo` in your local system than you will not face the issue mentioned above 
+
+## Create a Pull Request
+
+After making changes and doing a `git add` to stage them, you'll need to commit them. We recommend using the below format.
+```
+$ git commit -m "finos/a11y-theme-builder#< issue no.> : <commit message>"
+```
+Once all changes have been committed, push the changes.
+
+```
+$ git pull origin <branch-name>
+$ git push origin <branch-name>
+```
+Then on Github, navigate to the `finos/a11y-theme-builder` repository and create a pull request from your recently pushed changes to the `dev` branch.
+
+### Registration for LFX EasyCLA
+
+When you create your first pull request for FINOS A11y Theme Builder, you will be asked to agree to a Contributors License Agreement. You can find more information on this topic [here](https://github.com/finos/a11y-theme-builder/blob/main/CONTRIBUTE.md#finos-restrictions) 
+
+### Mention for Review
+
+In Theme Builder, all pull requests must be reviewed by at least one maintainer. In general, you should try to select a reviewer that is either very familiar with the issue that you are working on or very familiar with the code or functionality that you are changing. If in doubt, tag your mentor in a comment in the PR asking for guidance so that they will be notified of your question. You can find more information on this topic [here](https://github.com/finos/a11y-theme-builder/blob/main/CONTRIBUTE.md#contribution-rules)
+
 
 ## Understanding Server APIs
 
@@ -222,4 +270,22 @@ The APIs are under the `/api/` endpoint, with the following apis available:
 - **Return Errors**: 404 document :id was not found, 500
 - **Example**: DELETE /api/themes/theme5 => { id:"theme5", key1:themeData}
 
+## Creating Epics
+
+In general terms, an Epic is a reasonably large piece of work that is built from smaller pieces of work on which it depends.  These smaller pieces of work may themselves be Epics that have their own dependencies.  So if you think of an individual, well-defined, self-contained piece of work as being represented as an issue in an issue tracking system, an Epic is comprised of such issues.  The issues contained in an Epic may need to be completed in a general order and that order should be defined in the Epic.  In practice, Epics are usually feature/enhancement requests that summarize a piece of functionality that a user would like to see implemented in a project.  The Epic would describe the problem, the potential solution, and a plan for how that work could be achieved.  After the plan is formed, issues would be created in order to track each individual piece of work of which the plan consists.  The issues would then be assigned owners to complete the work.
+
+In Theme Builder, we prefer that Epics be created with the help of maintainers.  A maintainer creating an epic should prepend the key string `[EPIC]` to the Epic's title.  The maintainer should make sure that Tasks are defined in the Epic as individual pieces of work are defined.  Each Task should be tracked using an issue.  In that issue, all pieces of work on which the issue depends should be defined and, where possible, linked to.  The overall result, once this is accomplished, is that a user should be able to go to an Epic, see a summary of the work that the Epic represents, should be able to see the tasks that, when put together, achieve the end goal of the Epic, the order in which the tasks need to be undertaken, and what dependencies each task has.
+
+As an example, if an Epic is created to add a new user action to a user interface, it should define:
+
+* The goal behind the new action
+* A rough idea how the action could be implemented and any dependencies the acction may have
+* A list of tasks including:
+    * A design thinking task to define the user scenarios and personas
+    * A task to create the wireframes dependent on the design thinking task depicting any new components that may need to be created that the user would use to trigger the action.
+    * A task for each deliverable identified in the wireframe and design thinking tasks
+        * It is possible that such a deliverable could, itself, be an Epic if it is a significant piece of work with its own dependencies.
+    * A task for testing each deliverable
+
+If you have any questions about Epics, please [reach out to the community](README.md#learn-more-give-feedback) for assistance.