diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 5280dc0ea6..e22c3e7acf 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,4 +1,3 @@ - # Contributor Covenant Code of Conduct ## Our Pledge @@ -6,8 +5,7 @@ We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body type, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity +identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, @@ -39,23 +37,18 @@ Examples of unacceptable behavior include: ## Enforcement Responsibilities -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. +not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. ## Scope -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. ## Enforcement @@ -94,8 +87,7 @@ of actions. **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or +includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### 3. Temporary Ban @@ -105,9 +97,7 @@ sustained inappropriate behavior. **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. +private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. ### 4. Permanent Ban @@ -118,17 +108,17 @@ individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. +--- + ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], +This Code of Conduct is adapted from the **Contributor Covenant**, version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). -[homepage]: https://www.contributor-covenant.org - For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac8b210f61..7c8ceb133e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,98 +1,196 @@ # Contributing to FarmData2 # -FarmData2 welcomes participation and contributions. There are many ways to contribute to FarmData2 that we hope will engage and energize a broad and diverse community. This document outlines a few of the ways to contribute. +This document provides a step-by-step guide to fixing your first issue in FarmData2. While this guide is targeted at making a first contribution, the process it outlines is general and will apply to all code or documentation contributions. So you may find it helpful to return here if you continue to contribute. For ways to contribute other than fixing issues see the [HOW_TO](HOW_TO.md) document. -## Code of Conduct ## +## 1. Review FarmData2's Code of Conduct ## -To promote an open, welcoming, inclusive and harassment-free experience, all engagement with FarmData2 is governed by the community standards expressed in the [Contributor Covenent](CODE_OF_CONDUCT.md). +FarmData2 is committed to creating an open, welcoming, inclusive and harassment-free experience for all community members. Please review the Code of Conduct before engaging with the FarmData2 community. -## Licensing ## +- [FarmData2 Code of Conduct](CODE_OF_CONDUCT.md) -Content in the FarmData2 project is released under several different licenses as described in the [LICENSE file](LICENSE.md). In addition, that file describes the rights and responsibilities of contributors with regard to the their contributed content. The licensing structure of FarmData2 is designed to ensure that FarmData2 remains free and open source while protecting both the project and it community of contributors. Please review it carefully before contributing content to FarmData2. +## 2. Review the FarmData2's Licensing ## -## Connecting ## +We use a variety of licenses and agreements to ensure that FarmData2 remains free and open source while protecting both the project and its community of contributors. Please review the Licensing information below before contributing to the FarmData2 project. -Connect with the [FarmData2 community on Zulip](https://farmdata2.zulipchat.com/). +- [FarmData2 Licensing](LICENSE.md) -If you are unfamiliar with [Zulip](https://zulip.com/) it is a group chat application that blends the benefits of threaded discussions with live chat. Zulip is relatively easy to use once you understand the key ideas of [streams and topics](https://zulip.com/help/about-streams-and-topics). +## 3. Install and Run FarmData2 ## -## Developer Installation ## +Ensure that FarmData2 has been installed and is running. The following steps will assume that you are working within the FarmData2 development environment via a VNC Viewer or via noVNC in a browser. -Having a running version of FarmData2 is a prerequisite for many of the forms of participation described below. The [Install Directions] give step by step instructions for getting a developer installation of FarmData2 up and running. +- [Installing FarmData2](INSTALL.md) -[Install Directions]: INSTALL.md +## 4. Connect with the FarmData2 Community ## -## Participation ## +The FarmData2 community communicates via Zulip as its primary location for reaching out with questions or for additional information. -There are many ways to participate in FarmData2. Some of them are listed below. + 1. Visit the [FarmData2 community on Zulip](https://farmdata2.zulipchat.com/) + 2. Log in to Zulip using an existing Google, GitHub or GitLab account, or "Sign Up" using your e-mail. + 3. Say "Hello!" and tell us a little about yourself in the [Introduce Yourself Stream](https://farmdata2.zulipchat.com/#narrow/stream/270883-general/topic/Introduce.20Yourself). -#### Bug Reports #### +The [Getting Started with Zulip Page] from the [Zulip Help Center](https://zulip.com/help/) provides a quick introduction to using Zulip if you want a few pointers. -If you are are a user of FarmData2 and discover something that doesn't seem to be working correctly you can: +## 5. Find an Issue to Work On ## - * Reach out to the community on the [Zulip Developer Stream](https://farmdata2.zulipchat.com/#narrow/stream/271292-developers) to discuss what you have found and how to proceed. - * Search the [Issue Tracker] to see if the bug has been reported already. - * If it has, add a confirmed sighting or any additional information you have by commenting on the ticket. - * If it has not, open a new ticket and give a description of the issue, identify the platform on which you are running FarmData2 and describe the steps someone can use to observe the bug. +Visit the Issue Tracker to find an issue on which to work: -[Issue Tracker]: https://github.com/DickinsonCollege/FarmData2/issues +- [FarmData2 Issue Tracker](https://github.com/DickinsonCollege/FarmData2/issues) -#### Feature Requests #### +In particular, you can search the Issue Tracker for tickets with the following labels that indicate that the issue is a good place to get started: -If you are are a user of FarmData2 and have a new feature you would like to see you can: +- [![Good First Issue](media/GoodFirstIssueLabel.jpg)](https://github.com/DickinsonCollege/FarmData2/labels/good%20first%20issue) - The issues described in these tickets are the most approachable and do not require an in depth knowledge of the project or its technologies. They typically involve changes that do not affect the application's behavior. Often a familiarity with Markdown, HTML, and/or JavaScript is sufficient for addressing these issues. These issues provide a great way to get familiar with the process of making a contribution. - * Reach out to the community on the [Zulip Developer Stream](https://farmdata2.zulipchat.com/#narrow/stream/271292-developers) to discuss the feature you'd like to see and how to proceed. - * Search the [Issue Tracker] to see if the feature, or something close, has already been suggested by someone. - * If it has, add a comment lending support and possibly refining or giving your perspective on the idea. - * If it has not, open a new ticket and give a description of the new feature you would like to see. +- [![Good Second Issue](media/GoodSecondIssueLabel.jpg)](https://github.com/DickinsonCollege/FarmData2/labels/Good%20Second%20Issue) - The issues described in these tickets require some local understanding that is typically limited to one or two source files. They will usually require changes that affect behavior and thus may also require creation or modification of unit or end-to-end tests. Thus, greater familiarity with Javascript, Vue.js and/or Cypress tests may be required. These issues provide a great way to dig a little deeper,though still without requiring too deep a dive into the project. -#### Issue Gardening #### +## 6. Comment on the Ticket to Claim it ## -The project [Issue Tracker] contains tickets describing known issues with the project. The tickets for known issues are tagged with the label "bug". Each reported bug will have a detailed description of how the bug can be observed. Gardening includes activities such as: +When you find an issue that you would like to work on, make a comment on the ticket expressing your interest. Something like the following is sufficient: - * Verifying or clarifying these descriptions. - * Enhance the report by providing additional information about the bug (e.g. platforms on which is is or is not seen). - * Confirming that bug does (or does not) exist in the current version. + ``` + I would like to work on this isssue! + ``` -To participate by Gardening visit the [Issue Tracker] and find something of interest to verify, enhance or clarify. Try it out in your running version of FarmData2 and add a comment to the ticket with what you find. +One of the project maintainers will then assign the ticket to you. -#### Documentation #### +If you decide not to continue working on that issue, make another comment on the ticket letting us know so that we can assign it to someone else. -Update to any of the FarmData2 documentation are welcome. If you find typos, unclear or missing steps, poorly worded explanations, or have any other suggestions for how the documentation could be improved use the [workflow](#workflow) described below to create a pull request for your suggested changes. +## 7. Synchronize with the Upstream Repository ## -#### Bug Fix / Feature Implementation #### +Before beginning to address an issue you should *synchronize* your local repository and your `origin` repository (i.e. your fork on GitHub) with the `upstream` FarmData2 repository. This ensures that you begin your changes with the most up to date code and documentation. -Tickets in the [Issue Tracker] that are tagged _bug_ or _enhancement_ describe issues be fixed or new features to be added to FarmData2. The tag _good first issue_ appears on the most approachable tickets. If you find an issue to work on use the [workflow](#workflow) described below to create a pull request for your suggested bug fix or feature implementation. Information about the languages and technologies that are used in FarmdData2 and pointers to resources for learning more about them can be found in the [Technology On-boarding](#technology-on-boarding) section below. +Use the following commands in a Terminal window to synchronize your local repository and your `origin` repository with the `upstream`: -#### Other Thoughts #### + ``` + cd FarmData2 + git pull --ff-only upstream main + git push origin main + ``` -The above is not an exhaustive list of ways to participate in FarmData2. For some other ideas check out [50 Ways to be a FOSSer](http://foss2serve.org/index.php/50_Ways_to_be_a_FOSSer). If anything there seems interesting or if you have other ideas of your own please get in touch and we will be happy to have a discussion about how you might get involved. + Note: If you cloned your FarmData2 repository somewhere other than a `FarmData2` directory in the home directory you'll need to adjust the `cd` command above. All future sections of this document assume that the directory containing your FarmData2 repository is the current working directory. -## Technology Onboarding ## +If you encounter any problems, review the instructions for [Installing FarmData2](INSTALL.md) and then reach out to the [FarmData2 community on Zulip](https://farmdata2.zulipchat.com/). -Interacting with FarmData2 requires a basic familiarity with git and GitHub. FarmData2 development uses a fairly standard web technology stack including HTML, CSS, Bootstrap, JavaScript, and Vue.js. The front-end accesses FarmData2 data through the [FarmOS API](https://v1.farmos.org/development/api/) using the [Axios](https://github.com/axios/axios) library. End-to-end and component testing is done using the [Cypress framework](https://www.cypress.io/). +## 8. Create and Switch to a Feature Branch ## -If you are unfamiliar with one or more of these technologies the [ONBOARDING](ONBOARDING.md) document provides additional information about each, as well as resources and activities for learning about them. +All of the changes that you make to address an issue should be contained in a *feature branch*. -## Workflow ## +Use the following commands to create and switch to a feature branch. Be sure to replace the text `MyFeatureBranch` with a descriptive name based on the issue you are working on. -FarmData2 generally uses the [GitHub flow](https://guides.github.com/introduction/flow/) branching workflow and accepts contributions via Pull Requests. If you are new to git based branching workflows you may find this [in depth description GitHub flow](https://githubflow.github.io/) helpful. + ``` + git branch MyFeatureBranch + git switch MyFeatureBranch + git status + ``` + +The output of the `git status` command should confirm that you have created and switched to your new feature branch. -As a reference, the basic steps for working with GitHub Flow are as follows: +If you encounter any problems with this step, or any of the following ones, be sure to reach out to the [FarmData2 community on Zulip](https://farmdata2.zulipchat.com/). + +## 9. Solve the Issue ## - * Go to the [FarmData2 Repository] (the _upstream_) - * Fork the _upstream_ repository to your GitHub (the _origin_). - * [Clone] the _origin_ repository to your local machine. - * Set the _upstream_ remote for your local repository to point to the _upstream_ repository. - * Create a _feature branch_ from the _main_ branch your local machine. - * Make the edits to the documentation or the code in your _feature branch_. - * Commit your edits. - * If the contribution reflects the work of multiple people, ensure that everyone receives attribution by [Creating a commit with multiple authors]. - * Pull the most recent _upstream_ version of the _main branch_. - * Merge the updated _main branch_ into your _feature branch_. - * Push your _feature branch_ to the _origin_. - * Make a Pull Request for your _feature branch_ to the _upstream_. +Open the *VSCodium IDE* (or another editor of your choice) and modify the contents of the files in your local FarmData2 repository to address the issue. If your work requires multiple changes you should iterate between this step and and the following step until the issue is addressed. -[Clone]: https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/cloning-a-repository -[FarmData2 Repository]: https://github.com/DickinsonCollege/FarmData2 -[Creating a commit with multiple authors]: https://docs.github.com/en/free-pro-team@latest/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors +## 10. Add and Commit Your Fix to your Local Repo ## + +Each time you make changes that represent a *nameable unit of work* commit them to your local FarmData2 repository with a commit message that describes what has been done. For example, if you made a change that added a link to the farmOS project to the `README.md` file you would use the following commands: + + ``` + git status + git add README.md + git commit -m "Linked to the farmOS project" + git log + ``` + +If you have worked on your changes with someone else you will need to be sure to get them credit too by making a *co-authored commit* as follows: + ``` + git commit -m "Refactor usability tests. + > + > + Co-authored-by: NAME + Co-authored-by: AUTHOR-NAME " + ``` + You'll need to know your co-author(s) e-mail address or GitHub *no-reply email* so that you can provide it in the commit message. Note: The `>` characters appear wen you press *Enter* or *Return* in the Terminal because the string that is opened (`"`) after the `-m` is not terminated (`"`) until after the final co-author line. + +Inspect the output of the `git status` command to confirm that your are in the right place and the `git log` command to confirm that you have successfully committed your changes. + +## 11. Push your Feature Branch to your Origin Repo ## + +When you have fully addressed the issue you are working on, you will `push` your feature branch to your `origin` repository on GitHub. Pushing your changes to GitHub will allow you to make a Pull Request (below) that will invite the FarmData2 maintainers to see and review your work. + +Use the following commands to push your feature branch to your `origin` on GitHub. Be sure to replace `MyFeatureBranch` with the name of the branch that you created above. + + ``` + git status + git push origin MyFeatureBranch + git status + ``` + +Inspect the output of the `git status` commands to confirm that your are in the right place and that you have successfully pushed your feature branch. + +## 12. Make a Pull Request ## + +You'll now make a pull request to let the FarmData2 maintainers know that you have some changes that address the issue on which you were working. Use the following steps to create your pull request: + + 1. Visit your `origin` repository on GitHub. + 2. Click the green "Compare and Pull Request" button at the top of the page. + - If you do not see this button then see if GitHub's instructions for [Creating a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) will help. If you follow these directions the `base branch` should be the `main` branch of the `upstream` FarmData2 repo. The `compare branch` should be your feature branch in your `origin` repository. + 3. Write a title for your pull request that describes what it does. + 4. Fill in a more complete description of your pull request in body. + - At a minimum you should include a line that indicates the issue that has been addressed by your changes. For example, if your changes address ticket #123 in the issue tracker then add the line: + ``` + Closes #123 + ``` + Including this line ensures that the ticket in the issue tracker will be automatically closed if your changes are accepted. + 5. Click the "Create Pull Request" button. + - If your work is not complete, but you want to get feedback from the maintainers choose the "Create Draft Pull Request" option. + +## 13. Follow Up ## + +Once you submit a pull request you should keep an eye out for a reply from the project maintainer. This reply might: + - Congratulate you on your pull request being merged. + - Provide a request for further changes before your request can be merged. + - Ask questions about your approach or implementation. + - Etc. + +Prompt responses to the maintainers are always appreciated and improve the chances that your pull request (possibly with revision) will be merged. + +## 14. Update you Pull Request as Necessary ## + +If you received feedback on your pull request and changes were requested, you can update your pull request as follows: + 1. Make the requested changes in your local repository. + 2. Commit the changes to your feature branch. + 3. Push your feature branch to your `origin` repository on GitHub. + +When you commit and push changes to a feature branch for which a pull request has been the pushed changes are automatically a part of the pull request. There is no need to create a new pull request. + +## 15. Delete Your Feature Branch ## + +When your pull request is merged, or is closed without being merged, you can delete your feature branch. + +The following commands will delete your feature branch from your local repository: + + ``` + git branch + git branch -D MyFeatureBranch + git branch + ``` + +Use the output of the `git branch` commands to confirm that your feature branch has been deleted. + +You can delete your feature branch from your `origin` on GitHub using the web interface through your browser, or you can use the following command: + + ``` + git push origin --delete MyFeatureBranch + ``` + +You can use the web interface through your browser to confirm that the branch has been deleted from GitHub. + +## 16. Contribute More ## + +Now that you've made your first contribution, if you are ready for more you can: + - Head back to go back to step #5 of this document and start again! If you get into working on more complex issues and need to learn more about the FarmData2 project or the technologies that it uses be sure to: + - Check out the other [ways to contribute to FarmData2](docs/WaysToContribute.md). + - Check out the [RESOURCES page](RESOURCES.md). + - Reach out to the [FarmData2 community on Zulip](https://farmdata2.zulipchat.com/). + +Good luck and happy contributing! \ No newline at end of file diff --git a/INSTALL.md b/INSTALL.md index 5a5016d418..f13566ca05 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -12,27 +12,39 @@ FarmData2 is currently in the early stages of development and thus is not ready ## Developer Install ## -Before beginning this install please review the [CONTRIBUTING.md](CONTRIBUTING.md) document and in particular be sure to follow the links to the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) that sets the expectations for the FarmData2 community. +Before beginning this install please review the [Code of Conduct](CODE_OF_CONDUCT.md) that sets the expectations for the FarmData2 community and the [License Information](LICENSE.md) that describes FarmData2's licensing. ### Prerequisites ### -FarmData2 relies on a few prerequisites that will need to be installed on your computer. You will need to install - * docker Desktop - * git - * TigerVNC Viewer - -Full installation details for these tools can be obtained from the projects themselves on the following sites: - - * [Get Docker](https://docs.docker.com/get-docker/) - * For Windows installs follow the "WSL 2 backend" directions (not the "Hyper-V backend"). - * Test your install using the command: `docker run hello-world` - * You should be able to run this command without `root` or `admin` privileges. - * [Installing git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - * Test your install using the command: `git --version` - * TigerVNC Viewer - Download and install the viewer for your platform: - * Windows: [vncviewer64-1.12.0.exe](https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/vncviewer64-1.12.0.exe/download) - * MacOS: [TigerVNC-1.12.0.dmg](https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/TigerVNC-1.12.0.dmg/download) - * Linux: [tigervnc-1.12.0.x86_64.tar.gz](https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/tigervnc-1.12.0.x86_64.tar.gz/download) +FarmData2 relies on a few prerequisites that will need to be installed on your computer. You will need to install: + - git + - docker Desktop + - TigerVNC Viewer + +Full installation details for these tools are provided by the projects themselves as described and linked below: + + - [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + - Test your install using the command: `git --version` + - Installing Docker Desktop + - Installation + - For Windows: + - First [install *WSL* (the *Windows Subsystem for Linux*)](https://learn.microsoft.com/en-us/windows/wsl/install). + - Then follow the instructions for installing [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/). Be sure to follow the directions for the "WSL 2 backend" (not the "Hyper-V backend"). + - For MacOS: + - Follow the instructions for installing [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/). Be sure to choose chose "Mac with Intel Chip" or "Mac with Apple Silicon" as appropriate for your Mac. If you are unsure, choose "About this Mac" from the Apple menu and check which "Chip" is in your Mac (Intel or Apple). + - For Linux: + - Follow the instructions for installing [Docker Desktop for Linux](https://docs.docker.com/desktop/install/linux-install/). + - Test your installation of Docker Desktop. + - Open a Terminal (in Windows be sure to use a WSL terminal) and use the command: + ``` + docker run hello-world + ``` + - You should be able to run this command without `root` or `admin` privileges. + - If successful, this command will generate some output indicating that it worked. + - TigerVNC Viewer - Download and install the TigerVNC viewer for your host operating system (Windows, Mac or Linux): + - Windows: [vncviewer64-1.12.0.exe](https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/vncviewer64-1.12.0.exe/download) + - MacOS: [TigerVNC-1.12.0.dmg](https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/TigerVNC-1.12.0.dmg/download) + - Linux: [tigervnc-1.12.0.x86_64.tar.gz](https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/tigervnc-1.12.0.x86_64.tar.gz/download) ### Getting FarmData2 ### @@ -44,27 +56,33 @@ To get started: 1. [Create a GitHub Account](https://github.com/join) (if you do not already have one). 1. [Fork the FarmData2 repository](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) into your own GitHub account. - 1. [Clone your fork](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/cloning-a-repository) of FarmData2 to your development machine. - 1. Change your directory to where you have cloned using `cd`. - 1. [Set your upstream remote](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork) to point to the main [FarmData2 repository](https://github.com/DickinsonCollege/FarmData2) at https://github.com/DickinsonCollege/FarmData2. + 1. Open a Terminal (be sure this is a WSL terminal in Windows), then: + 1. [Clone your fork](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/cloning-a-repository) of FarmData2. + 1. Change your directory to where you have cloned FarmData2 using `cd`. + 1. [Set your upstream remote](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork) to point to the main [FarmData2 repository](https://github.com/DickinsonCollege/FarmData2) at https://github.com/DickinsonCollege/FarmData2. ### Starting FarmData2 ### -To start FarmData2, ensure that docker is running and you are in the `docker` directory of the repository. Then, use the command below: -``` -./fd2-up.bash -``` - -This command will start up the docker containers that are used by FarmData2. There will be lots of output from this command and the first time you run it, it may take a while to complete as it pulls, downloads and extracts the docker images to your machine. You will know the command is complete when it outputs: -``` -FarmData2 started. -``` +To start FarmData2 +1. Ensure that Docker Desktop is running on your machine. +1. In a Terminal (a WSL terminal on Windows): + 1. Change to the `docker` directory of the FarmData2 repository. + 1. Use the command: + ``` + ./fd2-up.bash + ``` + This command will start up the Docker containers that are used by FarmData2. There will be lots of output from this command and the first time you run it, it may take a while to complete as it pulls and extracts the necessary docker images to your machine. You will know the command is complete when it outputs: + ``` + FarmData2 started. + ``` ### Connecting to the FarmData2 Development Environment ### FarmData2 provides a full featured Debian Linux based development environment. This development environment is automatically running inside one of the Docker containers that was started by the `./fd2-up.bash` script. -**All of the FarmData2 instructions and documentation assume that you are working within the FarmData2 development environment.** That said, developers experienced with tools like git, docker and docker-compose should not face any substantial barriers to development directly on Windows, MacOS or other Linux flavors (with a few exceptions where the development environment is required). +**All of the FarmData2 instructions and documentation assume that you are working within this FarmData2 development environment.** + +That said, developers experienced with tools like git, docker and docker-compose should not face any substantial barriers to development directly on Windows, MacOS or other Linux flavors. There are however a few exceptions where the development environment is required and those are noted in the appropriate places. #### Connecting via TigerVNC Viewer #### @@ -72,19 +90,21 @@ You can connect to the FarmData2 development environment using the TigerVNC View 1. Run your TigerVNC Viewer 2. Set the "VNC Server" field to: `localhost:5901` 3. Click "Connect" -4. If nothing happens and the TigerVNC Viewer quits, wait a moment and try again. Sometimes it takes a few moments for the VNC server in the container to start. +4. If nothing happens and the TigerVNC Viewer quits, wait a moment and try again. It typically takes a few moments for the VNC server in the container to start. + +When the TigerVNC Viewer connects to the FarmData2 Development environment a window will open displaying the Desktop of the Debian Linux system that is running in the docker container. #### Connecting via a Browser #### -You can also connect to the FarmData2 development environment using a browser. -1. Open a browser on the host OS +You can also connect to the FarmData2 development environment using a noVNC client through a web browser. +1. Open a web browser on the host OS 2. Visit the URL: `localhost:6901` 3. Click "Connect" 4. Use the NoVNC settings (on the left) to set the "Scaling Mode" to "Remote Resizing" -Note: When accessing the development environment via the browser, copying and pasting between the host OS and the development environment is tedious. However, if you work entirely inside the development environment it is quite functional. +Note: When accessing the development environment via the browser, copying and pasting between the host OS and the development environment using the noVNC clipboard is tedious. However, if you work entirely inside the development environment it is quite functional. -When the TigerVNC Viewer connects to the FarmData2 Development environment a window will open displaying the Desktop of the Debian Linux system that is running in the docker container. +When the noVNC client connects to the FarmData2 Development environment the Desktop of the Debian Linux system that is running in the docker container will appear in your browser window. #### Development Environment Credentials #### @@ -103,7 +123,7 @@ Configure the git CLI within the FarmData2 development environment by: 1. Open a Terminal 2. `git config --global user.email "you@your.email"` 3. `git config --global user.name "your github username"` -4. [Create a personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) in GitHub. +4. [Create a personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) in GitHub, if you don't have one already. * Set the "Expiration" to a reasonable duration. * Select the "repo" scope when creating the token. * Copy the token to the clipboard. @@ -118,7 +138,7 @@ Note: The git client in the FarmData2 development environment is set "store" you The FarmData2 repository contains a sample database with anonymized data from several years of operation of the [Dickinson College Farm](https://www.dickinson.edu/farm). This database is in the compressed file `docker/db.sample.tar.bz2` and needs to be expanded before it can be used. To install the sample database image: 1. Open a Terminal -2. `cd FarmDat2/docker` +2. `cd FarmData2/docker` 3. `./setDB.bash sample` When this command completes there should be a `db` directory in the `docker` directory. The files in this `db` directory are a mySQL database that contain the sample data. Note that you will only need to do this step once. But the above command can be used at any time to reset the database to its initial state. @@ -158,7 +178,7 @@ http://localhost The FarmData2 developer environment includes the VSCodium IDE. This IDE is pre-configured with all of the extensions necessary for FarmData2 development. You can open this IDE and the FarmData2 project by: 1. Clicking the VSCodium icon dock at the bottom of the desktop. 2. Choosing "Open Folder" from the "File" menu. -3. Selecting "FarmDat2". +3. Selecting "FarmData2". 4. Clicking the "Open" button. 5. Confirm that you "trust the authors of the files in this folder", if asked. 6. Choose "Explorer" from the "View" menu to see the `FarmData2` file tree. @@ -167,9 +187,9 @@ If you are using your own VSCode or VSCodium installation on your host OS your c ### Stopping and Starting FarmData2 ### -The above process of installing and stetting up the FarmData2 development environment only needs to be completed once. Once it is completed you will only need to start and stop the docker containers before and after each work session. +The above process of installing and setting up the FarmData2 development environment only needs to be completed once. Once it is completed you will only need to start and stop the docker containers before and after each work session. -From the `docker` directory in the repository you can: +In a Terminal (a WSL Terminal on windows) change into the `docker` directory in the FarmData2 repository. From there you can: * Stop FarmData2: ``` @@ -181,47 +201,6 @@ From the `docker` directory in the repository you can: ./fd2-up.bash ``` -## Technical Details ## - -Below are some additional details that may be important for advanced development but, at least at first, may be safely ignored. - -### Availability of phpMyAdmin ### - -For developers working on back-end services and the FarmData2 data model there is a phpMyAdmin service that can be connected to via a browser in the FarmData2 development environment at: - -``` -http://fd2_phpmyadmin -``` - -To see the live database being used log into phpMyAdmin using the credentials: - * Username: `farm` - * Password: `farm` - -You can also connect to phpMyAdmin as an administrator using the credentials: - * Username: `root` - * Password: `farm` - -Note: You may also connect to the phpMyAdmin service from a browser in your host OS (e.g. MacOS, Windows, Linux) using the URL: -``` -http://localhost:8181 -``` - -### Persistence ### - -The [`docker/fd2-up.bash`](docker/fd2-up.bash) and [`docker/fd2-down.bash`](docker/fd2-down.bash) scripts start and stop all of the containers necessary for FarmData2. Some key points about how information is persisted between container starts and stops are described below. The full details can be found in the [`docke/docker-compose.yml`](docker/docker-compose.yml) file. - -#### Writeable Layers #### - -When `./fd2-down.bash` is run `docker-compose` removes all of the containers, including their writeable layers. The containers are all recreated, including blank writeable layers, each time the `fd2-up.bash` is used. However, all of the FarmData2 data and code is mounted from the development machine and thus will persist between uses. You can find all of the details of the mounted volumes in the `docker-compose.yml` file. - -#### The FarmData2 Repository #### - -The `FarmData2` repository on the host machine is mounted into `/home/fd2dev/FarmData2` in the FarmData2 development container. The `FarmData2/contrib_modules` and the `FarmData2/farmdata2_modules` directories are mounted into the appropriate locations in the farmOS container. Thus, any changes made to the contents of the these directories either in the FarmData2 development environment or on the host machine will be reflected in the containers. - -#### The Database #### - -The farmOS/drupal database used by FarmData2 is stored in a Docker volume (`docker_farmos_db`)that is mounted into the FarmData2 development environment at `docker/db` and into the Maria DB container at `/var/lib/mysql`. Using the Docker volume rather than the host filesystem to persist the database provides a significant performance boost. - -#### The Dev Environment #### +### What Next? ### -The `home/fd2dev` directory in the FarmData2 development development environment is stored in a Docker volume (`docker_farmdev_home_fd2.x`). If it is necessary to make breaking changes to the development environment the version number of the container and the volume will be bumped in the `docker/docker-compose.yml` file which will create a new container and use a new blank volume the next time `fd2-up.bash` is run. +You now have a fully operational developer install of FarmData2 including the development environment. Check out the [CONTRIBUTING Document](CONTRIBUTING.md) for a step-by-step guide for how to make your first contribution to FarmData2. For other ways to contribute you can check out the [Ways to Contribute Document](docs/WaysToContribute.md). The [RESOURCES Document](RESOURCES.md) provides a list of more detailed reference information about FarmData2. \ No newline at end of file diff --git a/LICENSE.md b/LICENSE.md index a5070cb0c5..8a3280718f 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,37 +1,37 @@ -## FarmData2 Licensing Information ## +# FarmData2 Licensing Information # FarmData2 is a [Free Cultural Work]. This document outlines the licenses that apply to FarmData2 and the agreement which governs contributions. Complete copies of these documents can be be found in the [licenses directory]. All copies and forks of FarmData2 must be maintained in compliance with those licenses. [Free Cultural Work]: https://freedomdefined.org/Definition [licenses directory]: licenses -#### Contributions #### +## Contributions ## All contributions to FarmData2 will, as a part of FarmData2, be licensed under the applicable license agreements as described below. Thus, before any contribution will be accepted __the contributor must certify that they have the right to grant FarmData2 a license to use, modify and redistribute (with or without further modification) the contributed intellectual property__ under the applicable license agreement. This is done explicitly when when a contributor submits a Pull Request. Every pull request automatically contains a "Licensing Certification" section stating that the contributor certifies that the contribution satisfies the terms of the [Developer Certificate of Origin]. When posting content to any public forums of the project (for example, but not limited to, issue trackers, message boards or discussion areas), the act of posting is here in defined as an implicit certification by the contributor that their contribution satisfies the terms of the [Developer Certificate of Origin]. [Developer Certificate of Origin]: https://developercertificate.org/ -#### Intellectual Property #### +## Intellectual Property ## As described above, contributors license their intellectual property to FarmData2. Thus, they always retain the copyright to their intellectual property. -#### License Agreements #### +## License Agreements ## The code and documentation in FarmData2 are licensed using the following license agreements. -##### Code License ##### +### Code License ### All code in the FarmData2 project is licensed under the GNU General Public License v3 ([GPL-3.0]). [GPL-3.0]: https://www.gnu.org/licenses/gpl-3.0.md -##### Content License ##### +### Content License ### All other content, including code snippets posted in public forums, is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License ([CC-BY-SA-4.0]). [CC-BY-SA-4.0]: https://creativecommons.org/licenses/by-sa/4.0/ -#### Attribution #### +## Attribution ## Attribution of contributions to the FarmData2 repository are maintained in the logs of the git version control system. diff --git a/README.md b/README.md index 016bda435d..10fa10cc0f 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,35 @@ -## FarmData2 ## +# FarmData2 # FarmData2 is an application that supports the operation and certification requirements for small organic farming operations. -### Description ### +## Description ## FarmData2 is a web application for recording and reporting on crop and livestock production within the context of small organic farming operations. Crop production records include seeding, transplanting, harvest, cover crop, compost, fertilization, irrigation, pest scouting, and spray activities. Livestock production records track animals from birth to slaughter or sale and include pasture moves, periodic and veterinary care and logging of egg production. Records of packing, distribution and customer invoicing are also maintained. All records and reporting features are designed to closely align with organic certification requirements and to support the certification and recertification process. -### Connecting ### +## Connecting with the Community ## -Connect with the [FarmData2 community on Zulip](https://farmdata2.zulipchat.com/). +Have questions? Want to find something to do? Want to learn more? -If you are unfamiliar with [Zulip](https://zulip.com/) it is a group chat application that blends the benefits of threaded discussions with live chat. Zulip is relatively easy to use once you understand the key ideas of [streams and topics](https://zulip.com/help/about-streams-and-topics). +Connect with the FarmData community through the following channels: + - [FarmData2 streams on Zulip](https://farmdata2.zulipchat.com/) + - [FarmData2 Issue Tracker](https://github.com/DickinsonCollege/FarmData2/issues) + - [FarmData2 Pull Requests](https://github.com/DickinsonCollege/FarmData2/pulls) -### Installing FarmData2 ### +Not sure which channel to use? The [Communications Document](docs/Communications.md) describes each of these communications channels and how each is typically used. -If you are interesting in trying or using FarmData2 see the [INSTALL Document](INSTALL.md) for information about how to get started. +## Installing FarmData2 ## -### Contributing to FarmData2 ### +If you are interesting in trying, using or contributing to FarmData2 see the [INSTALL Document](INSTALL.md) for information about how to get started. -If you are interesting in contributing to the development of FarmData2 see the [CONTRIBUTING Document](CONTRIBUTING.md) for information about how to get started. +## Contributing to FarmData2 ## -### History ### +If you are interesting in contributing to the development of FarmData2 see the [CONTRIBUTING Document](CONTRIBUTING.md) for information about how to make your first contribution. The [Other Ways to Contribute Document](docs/WaysToContribute.md) has additional ideas for how you might engage with FarmData2. The [RESOURCES Document](RESOURCES.md) contains pointers to more detailed project documentation. + +## History ## FarmData2 is both a _second_ edition of it predecessor, FarmData, and the integration of _two_ related projects FarmData and AnimalData. These projects were conceived and built by Tim Wahls, Matt Steiman and many students to support operation of the Dickinson College Farm. The FarmData2 project was initiated as a part of curricular redesign in the Computer Science Department at Dickinson College. It is now an active part of several courses in the curriculum. It provides students in these courses with early and sustained opportunities to learn and practice modern software development within the context of an open source software community. -### Acknowledgements ### +## Acknowledgements ## FarmData2 is powered by the farmOS open source project. diff --git a/RESOURCES.md b/RESOURCES.md new file mode 100644 index 0000000000..95a5a9ee86 --- /dev/null +++ b/RESOURCES.md @@ -0,0 +1,69 @@ +# FarmData2 Resources # + +This document is a single source for information about FarmData2. It is organized as a list of links that point to documentation that addresses common tasks that arise in working on FarmData2. + +## Key Information ## + + - [Main Repository](https://github.com/DickinsonCollege/FarmData2) + - [Code of Conduct](CODE_OF_CONDUCT.md) + - [Licensing Information](LICENSE.md) + +## Communication ## + + - [How to Communicate in FarmData2](docs/Communications.md) + - The Communication Channels: + - [The FarmData2 community on Zulip](https://farmdata2.zulipchat.com/) + - [Issue Tracker](https://github.com/DickinsonCollege/FarmData2/issues) + - [Pull Requests](https://github.com/DickinsonCollege/FarmData2/pulls) + +## Getting Started ## + + - [Installing FarmData2](INSTALL.md) also includes: + - Starting and stopping FarmData2 + - Connecting to the development environment + - Login credentials for: + - the sample farm + - the development environment + - mariaDB / phpMyAdmin + +## Ways to Contribute ## + + - [Fixing Bugs or Adding Features](CONTRIBUTING.md) + - [Other Ways to Contribute](docs/WaysToContribute.md) + +## Learn FarmData2 Basics ## + + - [FarmData2 School](farmdata2/farmdata2_modules/fd2_school/README.md) + - [FarmData2 Organization](docs/Organization.md) + - [FarmData2's Technologies](docs/Technologies.md) + +## Front End Development ## + + - [The `fd2_example` Module](farmdata2/farmdata2_modules/fd2_example/README.md) + - [Creating FarmData2 Modules](farmdata2/farmdata2_modules/README.md) includes: + - Creating New Modules + - End-to-End Tests for Modules + - Using FarmData2 Library Functions + - Using FarmData2 Vue.js Components + - [The `fd2_config` Module](farmdata2/farmdata2_modules/fd2_config/README.md) + - [FarmData2 Front End Resources](farmdata2/farmdata2_modules/resources/README.md) includes: + - The FarmData2 JavaScript library + - The FarmData2 Vue.js Components + +## Back End Development ## + + - [The FarmData2 API](farmdata2/farmdata2_api/README.md) also includes: + - Using phpMyAdmin + +## The Sample Database ## + + - [The FarmData2 Sample Database](docker/sampleDB/README.md) also includes: + - Description of the data + - Building/rebuilding the databases + +## FarmData2 Infrastructure ## + + - [Overview of FarmData2 Containerization](docker/README.md) also includes: + - Descriptions of the Docker images + - Building/updating Docker images + \ No newline at end of file diff --git a/docker/README.md b/docker/README.md index cc51a6ec83..e60425c6a8 100644 --- a/docker/README.md +++ b/docker/README.md @@ -36,6 +36,26 @@ FarmData2 opts to pull all images from its own dockerhub repository to allow us The images that are used are specified in the `docker/docker-compose.yml` file. +## Persistence in Containers ## + +The [`docker/fd2-up.bash`](docker/fd2-up.bash) and [`docker/fd2-down.bash`](docker/fd2-down.bash) scripts start and stop all of the containers necessary for FarmData2. Some key points about how information is persisted between container starts and stops are described below. The full details can be found in the [`docke/docker-compose.yml`](docker/docker-compose.yml) file. + +### Writeable Layers ### + +When `./fd2-down.bash` is run `docker-compose` removes all of the containers, including their writeable layers. The containers are all recreated, including blank writeable layers, each time the `fd2-up.bash` is used. However, all of the FarmData2 data and code is mounted from the development machine and thus will persist between uses. You can find all of the details of the mounted volumes in the `docker-compose.yml` file. + +### The FarmData2 Repository ### + +The `FarmData2` repository on the host machine is mounted into `/home/fd2dev/FarmData2` in the FarmData2 development container. The `FarmData2/contrib_modules` and the `FarmData2/farmdata2_modules` directories are mounted into the appropriate locations in the farmOS container. Thus, any changes made to the contents of the these directories either in the FarmData2 development environment or on the host machine will be reflected in the containers. + +### The Database ### + +The farmOS/drupal database used by FarmData2 is stored in a Docker volume (`docker_farmos_db`)that is mounted into the FarmData2 development environment at `docker/db` and into the Maria DB container at `/var/lib/mysql`. Using the Docker volume rather than the host filesystem to persist the database provides a significant performance boost. + +### The Dev Environment ### + +The `home/fd2dev` directory in the FarmData2 development development environment is stored in a Docker volume (`docker_farmdev_home_fd2.x`). If it is necessary to make breaking changes to the development environment the version number of the container and the volume will be bumped in the `docker/docker-compose.yml` file which will create a new container and use a new blank volume the next time `fd2-up.bash` is run. + ## Building the Images The `docker/build-images.bash` script builds the images and pushes them to dockerhub. Run this script with no parameters to see a *usage* message describing how to build and push an image. @@ -53,4 +73,5 @@ When an image is modified the tag in its `repo.txt` file should be incremented. When a new tag is created and pushed, the `docker-compose.yml` file should also be updated to use the new tag for the image. This ensures that the latest images will be pulled for developers the next time they use `fd2-up.bash` to start FarmData2 after they synch with the upstream repository. -If significant changes are made to the `dev` container then it may also be necessary to bump the version number of the Docker volume that is used to store the fd2dev user's home directory. This will cause a new volume to be created for the user's home directory. \ No newline at end of file +If significant changes are made to the `dev` container then it may also be necessary to bump the version number of the Docker volume that is used to store the fd2dev user's home directory. This will cause a new volume to be created for the user's home directory. + diff --git a/docs/Communications.md b/docs/Communications.md new file mode 100644 index 0000000000..05ee3d0794 --- /dev/null +++ b/docs/Communications.md @@ -0,0 +1,16 @@ +# Communications in FarmData2 # + +FarmData2 uses three primary communications channels. Each channel serves a slightly different purpose. When communicating with the community try to pick the most appropriate channel. + + - [The FarmData2 community on Zulip][zulipCommunity] + - The Zulip community is the place where you can introduce yourself to the FarmData2 community, ask and answer questions about using FarmData2, developing FarmData2, the installation process, how to get started or technology. If you have a tentative idea for a new feature or are unsure if what you are seeing is a bug, the Zulip streams are a good place to have an initial conversation before creating a ticket in the Issue Tracker (below). If you are unsure who to ask or how to ask, start by reaching out on Zulip. The project maintainers monitor the Zulip streams and will respond to questions there. + + - [Issue Tracker][issueTracker] + - If you want to report a bug, want to request a new feature, have an idea about how address an existing issue, have started working on an issue and have questions, then the Issue Tracker is the channel to use. If you have thoughts or questions about an issue with an existing ticket in then adding comments to that ticket is the appropriate way to communicate. If you need to report a bug for which there is no ticket or you want to request a new feature, then creating a new ticket is the appropriate approach. There are links to additional information on reporting new bugs or requesting new features on the [HOW_TO](../HOW_TO.md) page. + + - [Pull Requests][pullRequests] + - If you have specific code or documentation changes that you want to contribute or partially coded bug fixes or implementations that you want to discuss then a pull request is the appropriate channel. For contributions that you believe are complete make a normal pull request. A project maintainer will review your request and will communicate with you through comments on the pull request if revisions are needed. If your changes are not complete but you have questions or would like input from a project maintainer then make a *draft pull request*. Explain the purpose of your pull request in the body and include a link to the ticket for the issue you are addressing (e.g. Closes #123). Then add a comment to the pull request asking the specific question about your code or documentation. + +[issueTracker]: https://github.com/DickinsonCollege/FarmData2/issues +[pullRequests]: https://github.com/DickinsonCollege/FarmData2/pulls +[zulipCommunity]: https://farmdata2.zulipchat.com/ \ No newline at end of file diff --git a/docs/Organization.md b/docs/Organization.md new file mode 100644 index 0000000000..e48da57f74 --- /dev/null +++ b/docs/Organization.md @@ -0,0 +1,17 @@ +# FarmData2 Organization + +This document discusses the overall organization of the FarmData2 repository. It outlines the major parts of the project, the technologies used in each part, and points to more specialized documentation on each part. + +FarmData2 can is broadly organized into the following areas: + +- **Infrastructure** - The infrastructure provides the tools and resources necessary to get a FarmData2 instance up and running. It uses Docker, docker-compose and bash scripts. Details of the infrastructure can be found in: + - [the `README` in the `docker` directory](../docker/README.md) + +- **Sample Database** - The sample database provides developers with a pre-populated anonymized data from the Dickinson College farm. The sample data covers one full growing season and half of the following season. Details of the sample database, including the data it contains, how to re-build it and how to expand it can be found in: + -[the `README` in the `sampleDB` directory](../docker/sampleDB/README.md) + +- **FarmData2 Modules** - The FarmData2 modules are the user-facing pages that appear in the farmOS user interface when FarmData2 is installed (e.g. the *Barn Kit*, *Field Kit* and their sub-tabs such as the *Seeding Report* and *Seeding Input*). Each FarmData2 module is defined a single HTML page that uses HTML, CSS, JavaScript, Vue.js and Bootstrap to create the user interface and to send/receive data. The individual pages are themselves contained in Drupal modules so that they can be loaded into the farmOS application (which is based on Drupal). Details of the FarmData2 modules can be found in: + - [the `README` in the `farmdata2/farmdata2_modules` directory](../farmdata2/farmdata2_modules/EADME.md) + +- **FarmData2 API** - FarmData2 often requires specific collections of data that cannot be retrieved efficiently using the API provided by the underlying farmOS project. Thus, FarmData2 provides a custom API that allows FarmData2 modules to easily retrieve the data that they need. The API endpoints are typically specialized and tightly coupled to the reports and input forms. Note that the FarmData2 API is used only from reading data. All writing of data is done via the farmOS API to ensure that all data stored is fully farmOS compatible. The details of the FarmData2 API can be found in: + - [the `README` in the `farmdata2/farmdata2_api` directory](../farmdata2/farmdata2_api/README.md) \ No newline at end of file diff --git a/ONBOARDING.md b/docs/Technologies.md similarity index 86% rename from ONBOARDING.md rename to docs/Technologies.md index bf547a4338..61031ba14a 100644 --- a/ONBOARDING.md +++ b/docs/Technologies.md @@ -1,29 +1,35 @@ -# Onboarding to FarmData2 # +# Overview of FarmData2 Technologies # -This document provides an overview of the technologies used in FarmData2, describes the roles that they play and provides resources for learning the essentials of each. +This document provides an overview of the technologies used in FarmData2, describes the roles that they play and provides some resources for learning the essentials of each. -Interacting with FarmData2 requires a basic familiarity with git and GitHub. FarmData2 development uses a fairly standard web technology stack including HTML, CSS, Bootstrap, JavaScript, and Vue.js. The front-end accesses FarmData2 data through the [FarmOS API](https://v1.farmos.org/development/api/) using the [Axios](https://github.com/axios/axios) library. End-to-end testing is done using the [Cypress framework](https://www.cypress.io/). The automation, configuration and back-end development of FarmData2 use a number of other technologies including Drupal, drush, FarmOS, Docker, docker-compose and bash scripting. +## Overview ## + +Interacting with FarmData2 requires a basic familiarity with git and GitHub. FarmData2 development uses a fairly standard web technology stack including HTML, CSS, Bootstrap, JavaScript, and Vue.js. The front-end uses [Axios](https://github.com/axios/axios) to accesses FarmData2 data in a [MariaDB](https://mariadb.org/) database through the [FarmOS API](https://v1.farmos.org/development/api/) and a custom [Express API](https://expressjs.com/). End-to-end testing is done using the [Cypress framework](https://www.cypress.io/). The automation, configuration and back-end development of FarmData2 use a number of other technologies including Drupal, drush, FarmOS, Docker, docker-compose and bash scripting. This document is intended to be used in two ways. When you are new to FarmData2, it is recommended that you work through this document from the top down. However, it is not essential that you fully master every tool and technology on the first pass. Rather once you feel basically comfortable with a tool or technology (or if you already know it) skip to the next one. Then later, while working on FarmData2 you can return to this document and jump directly to the relevant section(s) to find a reference or to learn a little bit more as needed. ## Preliminaries ## -Before continuing, If you haven't already, please review the [README](README.md), the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md), the [LICENSE](LICENSE.md) and the [CONTRIBUTING](CONTRIBUTING.md) documents as they provide information that is important to getting started and to maintaining the FarmData2 community. +Before continuing, If you haven't already, please review the [README](../README.md), the [CODE_OF_CONDUCT](../CODE_OF_CONDUCT.md), the [LICENSE](LICENSE.md) and the [CONTRIBUTING](../CONTRIBUTING.md) documents as they provide information that is important to getting started and to maintaining the FarmData2 community. + +### Installation ### + +The [INSTALL.md](INSTALL.md) file contains the instructions for doing a [Developer Install](INSTALL.md#developer-install). After you complete the developer install FarmData2 will be setup and ready for you to work on. ## Communications ## The FarmData2 community uses [Zulip](https://zulip.com/) as it communication platform. Zulip is a group chat application that blends the benefits of asynchronous threaded discussions (e.g. a forum) with live chat. -Connecting with the [FarmData2 community](https://farmdata2.zulipchat.com/) on Zulip provides a place to ask questions of the project managers and the broader developer community. +Connecting with the [FarmData2 community on Zulip](https://farmdata2.zulipchat.com/) provides a place to ask questions of the project managers and the broader developer community. - Resources: - [Streams and Topics](https://zulip.com/help/about-streams-and-topics): An introduction to the two key features of Zulip. Once you understand streams and topics Zulip is relatively easy to use. - [Zulip Home Page](https://zulip.com/): This page has a quick tour of Zulip's features that you can click through. - [User Documentation](https://zulip.com/help/): A comprehensive set of documentation on Zulip's use and features. -## Prerequisites ## +## Version Control and Repositories ## -The FarmData2 documentation and resources assume a basic facility with git, GitHub and a familiarity with the GitFlow branching workflow. You'll need to understand the steps outlined in the [FarmData2 Workflow](CONTRIBUTING.md#workflow). +The FarmData2 documentation and resources assume a basic facility with git, GitHub and a familiarity with the GitFlow branching workflow. You'll need to understand the steps outlined in the [CONTRIBUTNG](../CONTRIBUTING.md) document. The following resources can be useful for learning what you'll need to know about git and GitHub: @@ -35,25 +41,22 @@ The following resources can be useful for learning what you'll need to know abou - [Git Immersion](https://gitimmersion.com/): A tutorial walks through a series of short hands-on exercises that provide practice with the key features of git. - [Pro Git Book](http://git-scm.com/book/en/v2) | [Learn Git Tutorial](https://www.tutorialspoint.com/git/index.htm): More detailed and comprehensive coverage of Git's features and use. -## Quickest Start ## - -FarmData2 makes use of the following key technologies. HTML, CSS and Bootstrap, JavaScript with Vue.js and Axios, and Cypress for testing. If you are familiar all or most of those it may be sufficient to start by having a look at any of the modules in [farmdata2_modules/fd2_tabs](https://github.com/DickinsonCollege/FarmData2/tree/main/farmdata2_modules/fd2_tabs). The [fd2_example/README.md](https://github.com/DickinsonCollege/FarmData2/blob/main/farmdata2_modules/fd2_tabs/fd2_example/README.md) provides the essential information about how to add and test new FarmData2 features. - ## FarmData2 School ## -FarmData2 has been used in a number of undergraduate computer science courses and activities have been developed to guide students through an introduction to FarmData2 and the technologies that it uses. If you are new to open source and FarmData2 or to any of the technologies that FarmData2 uses, working through these activities will be an efficient way to get up to speed. If you are a more experienced developer you might just pick and choose from these activities, or skip over them completely to the more general resources in the sections below. If you are an instructor for a course, these activities can provide a way to on-board your students to the project. Please get in touch on Zulip if you are an instructor interested in using FarmData2 in a course, we will be happy to help. +FarmData2 has been used in a number of undergraduate computer science courses and activities have been developed to guide students through an introduction to front end development in FarmData2. If you are new to open source and FarmData2 or to any of the technologies that FarmData2 uses, working through these activities will be an efficient way to get up to speed. If you are a more experienced developer you might just pick and choose from these activities, or skip over them completely to the more general resources in the sections below. If you are an instructor for a course, these activities can provide a way to on-board your students to the project. Please get in touch on Zulip if you are an instructor interested in using FarmData2 in a course, we will be happy to help. -The FarmData2 School Activities and associated information can be found in the [README.md](https://github.com/DickinsonCollege/FarmData2/tree/main/farmdata2_modules/fd2_tabs/fd2_school/README.md) in the [FarmData2 School Module](https://github.com/DickinsonCollege/FarmData2/tree/main/farmdata2_modules/fd2_tabs/fd2_school) +The FarmData2 School Activities and associated information can be found in the [README.md](https://github.com/DickinsonCollege/FarmData2/tree/main/farmdata2/farmdata2_modules/fd2_school/README.md) in the [FarmData2 School Module](https://github.com/DickinsonCollege/FarmData2/tree/main/farmdata2/farmdata2_modules/fd2_school). -## Additional Resources ## +## Development Environment ## -### Installation ### +### Editors ### -The [INSTALL.md](INSTALL.md) file contains the instructions for doing a [Developer Install](INSTALL.md#developer-install). After you complete the developer install FarmData2 will be setup and ready for you to work on. +The FarmData2 code and documentation can be edited with any editor. However, for convenience, the FarmData2 installation includes ... -### Editors ### +TODO: Write this for VSCodium. -The FarmData2 code and documentation can be edited with any editor. However, for convenience, the FarmData2 installation includes a browser-based integrated development environment (IDE) based on [Eclipse Theia](https://theia-ide.org/). + +a browser-based integrated development environment (IDE) based on [Eclipse Theia](https://theia-ide.org/). To access the Theia IDE once the [FarmData2 development environment is running](INSTALL#developer-install), just open a browser tab and go to: ``` @@ -70,12 +73,14 @@ The explorer on the left will show the contents and structure of the FarmData2 r - [How to use Eclipse Theia as an IDE](https://eclipsesource.com/blogs/2019/10/04/how-to-use-eclipse-theia-as-an-ide/): An overview of Theia and its use ad an Integrated Development Environment. As FarmData2 matures, utilities (e.g. linters and formatters) will be added to the provided Theia IDE. If you choose to use a different editor, all such utilities will be documented in the [INSTALL.md](INSTALL.md) file so that you can install the appropriate plugins for your editor. +--> + -### Front-End Technologies ### +## Front-End Technologies ## The majority of development for FarmData2 is front-end (i.e. browser-based). This section outlines the key technologies that are used for this development. -#### HTML #### +### HTML ### [Hypertext Markup Language (HTML)](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference) is the base language that is used to create web pages. It defines the structure of a page and allows page _elements_ (e.g. headings, paragraphs, lists, images, etc.) to be _tagged_ and labeled with _attributes_. The way that an element is tagged and labeled allows the browser (with [CSS](#css)) to determine how the content of the element should be displayed. Elements and attributes also allow [JavaScript](#javascript), [Vue.js](#vue.js) and [Cypress](#cypress) to interact with the page style, structure and content. @@ -86,7 +91,7 @@ The majority of development for FarmData2 is front-end (i.e. browser-based). Th - [Introduction to HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML): A collection of guides and assessments that give a comprehensive introduction to HTML. - [HTML Reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference): A comprehensive reference to all of the HTML _elements_ and _attributes_. -#### CSS #### +### CSS ### [Cascading Style Sheets (CSS)](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference) is a language for specifying how an HTML document should be presented (i.e. how it is displayed by the browser). CSS uses _rules_ to apply styles to HTML _elements_. Each CSS rule _selects_ HTML elements to which it applies, specifies the _properties_ of the element that are to be styled (e.g. color, font-family, etc.) and gives a _value_ that indicates how they are to be styled (e.g. blue, cursive). [JavaScript](#javascript) can interact with CSS rules, properties and values to dynamically change how (and if) HTML elements are displayed. @@ -96,7 +101,7 @@ The majority of development for FarmData2 is front-end (i.e. browser-based). Th - [Learn to style HTML using CSS](https://developer.mozilla.org/en-US/docs/Learn/CSS): A collection of modules that give a comprehensive introduction to CSS. - [CSS reference](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference): A comprehensive reference to all of the CSS _properties_ and _values_. -#### JavaScript #### +### JavaScript ### [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference) is a programming language that can be used to add interactivity to HTML pages. JavaScript can add or remove HTML elements, change CSS styles and respond to events (e.g. button clicks, text entry). JavaScript is also used to produce dynamic content by exchanging information with web services through Application Programming Interfaces (APIs). For example, when a user of FarmData2 saves or retrieves information about plantings or harvests it is done by JavaScript code using an API (see [FarmOS API](#farmos-api)). @@ -108,7 +113,7 @@ The majority of development for FarmData2 is front-end (i.e. browser-based). Th - [JavaScript - Dynamic client-side scripting](https://developer.mozilla.org/en-US/docs/Learn/JavaScript): A collection of modules that give a comprehensive introduction to JavaScript. - [JavaScript Reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference): A comprehensive reference to all of the JavaScript language features. -#### Vue.js #### +### Vue.js ### [Vue.js](https://vuejs.org/) is a JavaScript framework for simplifying the creation of interactive web applications. Creating highly interactive applications using HTML, CSS and JavaScript is possible, but some of the details become repetitive and tedious. Vue.js simplifies many of the common operations by allowing parts of the displayed page to be _bound_ to a data object. In that way, when JavaScript code changes the data object the _view_ of that data displayed in the browser is automatically updated. @@ -119,7 +124,7 @@ The majority of development for FarmData2 is front-end (i.e. browser-based). Th - [Components Basics](https://vuejs.org/v2/guide/components.html): A textual introduction to Vue Components. - [FarmData2 Vue Component Details](https://github.com/DickinsonCollege/FarmData2/blob/main/farmdata2_modules/fd2_tabs/fd2_example/README.md): Information on specifically how FarmData2 uses and tests Vue Components. -#### FarmOS API #### +### FarmOS API ### The FarmData2 front end exchanges data with the server using the [FarmOS V1 API](https://v1.farmos.org/development/api/) ). JavaScript code using the [Axios](https://github.com/axios/axios) library requests data from FarmOS (e.g. a list of fields) or sends new data to FarmOS (e.g. a new planting). When data is received from FarmOS, the Vue.js object is updated, which in turn updates what is displayed in the browser. Conversely, when the user enters data in the browser, that data updates the Vue.js object and that information is used to make requests to the server. @@ -131,18 +136,22 @@ The FarmData2 front end exchanges data with the server using the [FarmOS V1 API] - [FarmOS V1 API](https://v1.farmos.org/development/api/): Documentation for Version 1 of the FarmOS API. - [Hoppscotch](https://hoppscotch.io/): A tool for experimenting with API calls. This can be useful in figuring out how to request what you want from the FarmData2 API and how its responses are formatted. -#### Bootstrap #### +### FarmData API ### + +TODO: Write this and point to documentation. + +### Bootstrap ### [Bootstrap](https://getbootstrap.com/) is a framework and CSS component library used by farmOS, and thus by FarmData2, to provide stylized HTML components. Polished production FarmData2 modules will use Bootstrap components instead of basic HTML elements so that FarmData2 integrates visually into the farmOS interface. - Resources: - [Introduction to Bootstrap](https://getbootstrap.com/docs/5.0/getting-started/introduction/): Comprehensive documentation for the Bootstrap framework. -#### Cypress #### +### Cypress ### The functionality of FarmData2 is tested using the [Cypress framework](https://www.cypress.io/). The tests in FarmData2 consist of end-to-end tests and component tests. The end-to-end tests run against the developer instance of FarmData2 and check the functionality of the pages. The component tests check the behavior of custom components that appear in FarmData2, in isolation from the running instance. FarmData 2 provides support for running both types of Cypress tests in a Docker container that eliminates the need to install or configure Cypress. See the documentation in the [farmdata2_modules/fd2_tabs/fd2_example/README.md](https://github.com/DickinsonCollege/FarmData2/blob/main/farmdata2_modules/fd2_tabs/fd2_example/README.md) file for information about running Cypress tests in FarmData2. -##### End-to-End Tests ##### +#### End-to-End Tests #### The Cypress end-to-end test framework works by controlling the web browser. A test typically consists of a series of steps that are automated by the Cypress tests, called _spec_s. A typical spec consist of the steps: 1. Setup the test (e.g. login, prime the database) @@ -160,7 +169,8 @@ The Cypress end-to-end test framework works by controlling the web browser. A te - [should](https://docs.cypress.io/api/commands/should.html#Syntax): Documentation for the `should` statement that is used to make assertions in Cypress tests. - [Assertions](https://docs.cypress.io/guides/references/assertions): A reference for all of the assertions (e.g. assertions and chainers for should) that can be used in Cypress tests. - [FarmData2 Cypress Tests Details](https://github.com/DickinsonCollege/FarmData2/blob/main/farmdata2_modules/fd2_tabs/fd2_example/README.md): Information on specifically how FarmData2 uses Cypress tests. -##### Component Tests ##### + +#### Component Tests #### Cypress component tests work by mounting a Vue Component into a browser and allowing tests to interact with it in isolation from the application. A typical component test will: 1. Configuring and mounting the component into the test framework. @@ -175,9 +185,9 @@ Cypress component tests work by mounting a Vue Component into a browser and allo - [Vue Test Utils API](https://vue-test-utils.vuejs.org/api/): API documentation for all of the functionality of the Vue Test Utils. - [FarmData2 Cypress Tests Details](https://github.com/DickinsonCollege/FarmData2/blob/main/farmdata2_modules/fd2_tabs/fd2_example/README.md): Information on specifically how FarmData2 uses Cypress tests. -### Project Automation ### +## Project Automation ## -#### docker #### +### docker ### The developer install of FarmData2 relies on docker containers running: - the core FarmData2 system including farmOS and Drupal. @@ -188,26 +198,34 @@ The developer install of FarmData2 relies on docker containers running: All of the docker related configuration and source files are found in the [docker](https://github.com/DickinsonCollege/FarmData2/tree/main/docker) directory. -#### docker-compose #### +### docker-compose ### FarmData2 uses docker-compose to build custom docker images for farmOS and the TheiaIDE containers and to start and network all of the containers. See the `docker-compose.yml` file in the [docker](https://github.com/DickinsonCollege/FarmData2/tree/main/docker) directory. -#### bash scripting #### +### bash scripting ### Bash scripts are provided in the [docker](https://github.com/DickinsonCollege/FarmData2/tree/main/docker) directory to simplify the process of bringing up and taking down FarmData2. -### Back-End Technologies ### +## Back-End Technologies ## -#### farmOS #### +### farmOS ### FarmData2 is built as a set of customizations to [farmOS](https://farmos.org/). The majority of FarmData2's features are added as custom modules displayed in tabs within the farmOS interface. See the [README.md](https://github.com/DickinsonCollege/FarmData2/blob/main/farmdata2_modules/fd2_tabs/fd2_example/README.md) in the `fd2_example` module for a description of how FarmData2 modules are added to farmOS. -#### Drupal #### +### Express ### + +TODO: Write this and add links. + +### phpMyAdmin ### + +TODO: Write this and add links. + +### Drupal ### farmOS runs on top of Drupal. From the FarmData2 perspective this is largely transparent. As it is discovered that more information is necessary it will be added here. -#### drush #### +### drush ### For a few particular tasks related to initialization and configuration FarmData2 makes use of [drush](https://www.drush.org/latest/) to interact with the Drupal instance on which farmOS is running. As it is discovered that more information is necessary it will be added here. diff --git a/docs/WaysToContribute.md b/docs/WaysToContribute.md new file mode 100644 index 0000000000..9c2e7a39a9 --- /dev/null +++ b/docs/WaysToContribute.md @@ -0,0 +1,49 @@ +# Ways to Contribute to FarmData2 + +## Fixing Issues and Adding Features + +The most common way to contribute to FarmData2 is though fixing issues or adding new features. A complete guide to making these types of contributions is provided in the [CONTRIBUTING](../CONTRIBUTING.md) document. + +## Bug Reporting ## + +If you are a user of FarmData2 and discover something that doesn't seem to be working correctly you can: + + 1. Reach out to the community on the [Zulip Developer Stream](https://farmdata2.zulipchat.com/#narrow/stream/271292-developers) to discuss what you have found and how to proceed. + 2. Search the [Issue Tracker](https://github.com/DickinsonCollege/FarmData2/issues) to see if the bug has been reported already. + - If it has, add a comment to the ticket to let us know you have confirmed the bug or to add any additional information you think will be useful. + - If it has not, open a new ticket describing the bug. Your ticket should include: + - A description of the bug. + - A detailed set of step that another developer can use to observe the bug. + - What you observe that indicates that the bug occurred. Annotated screen shots can be particularly helpful here. + - What you expect the behavior or output to be if the bug is fixed. + - If relevant, information about the platform on which you are running FarmData2 and the browser(s) you have used to verify your bug. + +## Feature Requests ## + +If you are are a user of FarmData2 and have a new feature you would like to see you can: + + - Reach out to the FarmData2 community on the [Zulip Developer Stream](https://farmdata2.zulipchat.com/#narrow/stream/271292-developers) to discuss the feature you'd like to see and how to proceed. + - Search the [Issue Tracker](https://github.com/DickinsonCollege/FarmData2/issues) to see if the feature, or something close, has already been suggested by someone. + - If it has, add a comment to the ticket lending support and possibly refining or giving your perspective on the idea. + - If it has not, open a new ticket and give a description of the new feature you would like to see. + +## Bug Gardening ## + +The project [Issue Tracker](https://github.com/DickinsonCollege/FarmData2/issues) contains tickets describing known issues (bugs, feature requests, etc.) with the project. The tickets for known bugs are tagged with the label "bug". The ticket for each reported bug should have a detailed description of how the bug can be observed, what the expected output is and what the observed output is. + +Bug Gardening includes activities such as: + + - Confirming that bug does (or does not) exist in the current version. + - Verifying or improving the steps for observing a bug. + - Narrowing down examples that are used to illustrated the bug. + - Providing additional information about the bug (e.g. platforms on which is is or is not seen). + +To participate by Bug Gardening visit the [Issue Tracker](https://github.com/DickinsonCollege/FarmData2/issues) and find a ticket about something of interest to verify, enhance or clarify. Try it out in your running version of FarmData2 and add a comment to the ticket with what you find. + +## Documentation ## + +Updates to any of the FarmData2 documentation are welcome. If you find typos, unclear or missing steps, poorly worded explanations, or have any other suggestions for how the documentation could be improved use the process described in the [CONTRIBUTING](../CONTRIBUTING.md) document to submit your suggested changes as a pull request. + +## Other Ideas? ## + +The above is not an exhaustive list of ways to participate in FarmData2. For some other ideas check out [50 Ways to be a FOSSer](http://foss2serve.org/index.php/50_Ways_to_be_a_FOSSer). If anything there seems interesting or if you have other ideas of your own please reach out to the FarmData2 community on the [Zulip Developer Stream](https://farmdata2.zulipchat.com/#narrow/stream/271292-developers) and we will be happy to have a discussion about how you might get involved. \ No newline at end of file diff --git a/farmdata2/README.md b/farmdata2/README.md index 56edb3ee3b..0dc812409d 100644 --- a/farmdata2/README.md +++ b/farmdata2/README.md @@ -1,24 +1,52 @@ -# Resources +# FarmData2 Structure -This directory contains JavaScript library functions, CSS definitions and VueJS Components that are used throughout FarmData2. The `doc` directory contains documentation for these functions and components that is generated from the comments that they contain. If changes or additions are made to the set of functions or components in this directory, the documentation should be regenerated as described below under _Documentation Tools_ and _Generating Documentation_. +Development work on FarmData2 can be divided into two main areas discussed in this document: +- Front End (farmOS Modules/Tabs, Vue Components, Utility Libraries, etc.) +- Back End (Custom FarmData2 API endpoints) -## The Documentation +## Front End -To see the documentation open `doc/index.html` in a browser. +The front end for FarmData2 is contained in the `farmdata2_modules` directory. More information about front end development, documentation and testing can be found in the: + - [`README` in the `farmdata2_modules` directory](farmdata2_modules/README.md) -### Documentation Tools +## Back End + +The back end for FarmData2 is partially based on the farmOS API and partially based on the custom FarmData2 APi contained in the `farmdata2_api` directory. More information about back end development, documentation and testing can be found in the: + - [FarmOS V1 API](https://v1.farmos.org/development/api/) + - [`README` in the `farmdata2_api` directory](farmdata2_api/README.md) + +## Documentation + +Both the front end and back end of FarmData provide documentation. -The documentation for the Javascript library functions are generated using [JSDoc](https://github.com/jsdoc/jsdoc) and the documentation for the VueJS components is also generated using JSDoc with the [JSDoc for VueJS Plugin](https://github.com/Kocal/jsdoc-vuejs/tree/3.x). +### Viewing Documentation -The versons that are installed in the Development Environment can be found in the `docker/dev/Dockerfile`. +To see the documentation open `farmdata2/doc/index.html` in a browser. + +Documentation is not stored in the repository and must be generated locally (above). ### Generating Documentation -To generate the documentation: +To generate the documentation within the development environment: + +1. Ensure that you are in the `farmdata2` directory. +2. Run the script `./generate_docs.bash` + +The documentation files will be generated in the `doc` directory within the `farmdata2` directory. + +### Writing Tests + +The details about how tests are written can be found in the `README` files for the front end and back end development provided above. + +### Documentation Tools + +The documentation for FarmData2 is generated using [JSDoc](https://github.com/jsdoc/jsdoc) and the documentation for the VueJS components uses the [JSDoc for VueJS Plugin](https://github.com/Kocal/jsdoc-vuejs/tree/3.x). All necessary tools for generating the documentation are included in the development environment but should you want to install them on you host machine, the versions that are installed in the development environment can be found in the `docker/dev/Dockerfile`. + +### Running Tests + +Details about running the front end and back end tests can be found in the `README` files for the front end and back end development provided above. -1. Change into the `resources` directory. -2. `./doc.bash` +### Writing Tests -The documentation files will be generated in the `doc` directory within the `resources` directory. +Details about writing front end and back end tests can be found in the `README` files for the front end and back end development provided above. -If new components or js file are added, the `doc.bash` script may also need to be updated to incorporate them. diff --git a/farmdata2/farmdata2_api/README.md b/farmdata2/farmdata2_api/README.md new file mode 100644 index 0000000000..3da6153ecd --- /dev/null +++ b/farmdata2/farmdata2_api/README.md @@ -0,0 +1,32 @@ +# The FarmData2 API + +TODO! + +- Will cover: + - Adding a function to the FarmData2/farmOS API library + - Using Hoppscotch to manually test API endpoints + - Writing unit tests for a FarmData2/farmOS API library function + - Adding a new FarmData2 API endpoint + - Documenting a FarmData2 API endpoint + - Writing unit tests for a FarmData2 API endpoint + +### Availability of phpMyAdmin ### + +For developers working on back-end services and the FarmData2 data model there is a phpMyAdmin service that can be connected to via a browser in the FarmData2 development environment at: + +``` +http://fd2_phpmyadmin +``` + +To see the live database being used log into phpMyAdmin using the credentials: + * Username: `farm` + * Password: `farm` + +You can also connect to phpMyAdmin as an administrator using the credentials: + * Username: `root` + * Password: `farm` + +Note: You may also connect to the phpMyAdmin service from a browser in your host OS (e.g. MacOS, Windows, Linux) using the URL: +``` +http://localhost:8181 +``` \ No newline at end of file diff --git a/farmdata2/farmdata2_modules/README.md b/farmdata2/farmdata2_modules/README.md new file mode 100644 index 0000000000..bab5b5e2a7 --- /dev/null +++ b/farmdata2/farmdata2_modules/README.md @@ -0,0 +1,232 @@ +# FarmData2 Modules # + + + +FarmData2 is built using Drupal modules that run within FarmOS. The _FieldKit_ and _BarnKit_ tabs in the FarmData2 interface are created by modules. The _FD2 Example_ tab is created by a sample module and provides canonical examples of many of the operations and UI elements used in the _FieldKit_ and _BarnKit_ tabs. The _FD2 School_ tab is created by a module used just for the FarmData2 School onboarding materials. + +## FarmData2 Module Structure ## + +As mentioned, each of the tabs in the FarmData2 interface are created by Drupal modules. Each FarmData2 module is defined in its own directory within the `farmdata2_modules/fd2_tabs` directory (e.g. `fd2_barn_kit`, `fd2_example`, `fd2_field_kit`). All modules should be named with the prefix `fd2_`. This keeps them together and makes them easier to find within the farmOS admin interface. + +A FarmData2 module named `fd2_xyz` would include a folder within `farmdata2_modules/fd2_tabs` named `fd2_xyz`. That folder will contain at least the following files and directories, where `fd2_xyz`, `abc` and `pqr` are simply place holders and should be replaced with module-specific names. +- `fd2_xyz.info`: Defines the module `fd2_xyz` so that it is recognized by Drupal. +- `fd2_xyz.module`: Contains the PHP implementation of the `fd2_xyz` module. This code determines where and when the tab is visible based on the user's role (e.g. `admin`, `manager`, `worker` or `guest`). It also defines the sub-tabs and their content. +- A folder for each sub-tab in the module. For example for a sub-tab `abc` there will be a folder named `abc` with the following contents: + - `abc.html`: The content for a sub-tab `abc` within the `fd2_xyz` module (e.g. `info.html`, `api.html`). + - `abc.spec.js`: Test file containing end-to-end tests for the `abc.html` page. The end-to-end tests are written using the Cypress testing tools (more info below). If multiple test files are used for the `abc.html` file, they should be named `abc.pqr.spec.js` where `pqr` clarifies the testing performed by the file. Multiple additional periods and names can be used as necessary, but the filename of the test must end with `.spec.js` in order to be recognized by the FarmData2 Cypress configuration. +- `cypress`: A directory containing additional module-level end-to-end tests for the `fd2_xyz` module. These are tests that are important for the module but that are not associated with a specific sub-tab. These test files must also be named `*.spec.js` to be recognized by the FarmData2 Cypress configuration. + +### Hiding the _FD2 Example_ Tab ### + +The _FD2 Example_ tab is created by the `fd2_example` module and is enabled by default by the [developer install](https://github.com/DickinsonCollege/FarmData2/blob/main/INSTALL.md#developer_install). This module and tab provide a sandbox for learning and experimentation with FarmData2 modules. The associated _FD2 Example_ tab will not appear in production installs. Developers wanting to mimic a production environment for demonstrations can hide the _FD2 Example_ tab by disabling the `fd2_example` module as follows: + +1. Log into FarmData2 as `admin` +1. Click `Manage` +1. Click `Modules` +1. Click `FarmData2` in the left column. +1. Click to turn the `FarmData2 Example` module off. +1. Click `Save configuration` + +When returning to the home screen the _FD2 Example_ tab should no longer be visible. The _FD2 Example_ tab can be reenabled by a similar process. + +### Adding New Sub-Tabs to a FarmData2 Module ### + +Most FarmData2 front-end development will consist of adding a new sub-tab to one of the FarmData2 tabs (i.e. the _Field Kit_ or the _Barn Kit_). This section discusses how to add such a sub-tab. + +To add a new sub-tab to the `fd2_xyz` module: +1. Ensure that a development instance of FarmData2 is up and running. See [INSTALL.md](https://github.com/DickinsonCollege/FarmData2/blob/main/INSTALL.md) for full instructions. +1. Edit the `fd2_xyz.module` file to add a new `array` to the `$items` array for the new sub-tab. The `array` for the _UI_ tab (shown below) is a good example to work from: + ```php + 'UI', + 'type' => MENU_LOCAL_TASK, + 'page callback' => 'fd2_example_view', + 'page arguments' => array('ui'), + 'access arguments' => array('View FD2 Example'), + 'weight' => 120, + ); + + // ... omitted code ... + }; + // ... omitted code ... + ``` + - Four elements of the `array` must be customized for your new sub-tab: + - `farm/fd2-example/ui`: This is the URL to directly access the _UI_ sub-tab. Replace `ui` with the URL you want for your sub-tab. + - Note: This string also controls the placement of the _FD2 Example_ and _UI_ tabs. The _FD2 Example_ tab will appear on the _Farm_ menu, which is where the _Dashboard_ tab also appears. The _UI_ tab will appear as a sub-tab on the _FD2 Example_ tab. The value `farm` cannot be changed. But, `fd2-example` and `ui` can. In particular, they are not required to match the filenames. For example, `fd2-example` does not have to match the filename `fd2_example.module` and `ui` does not have to correspond to `ui.html`. However, it is a good convention to follow. + - `title`: This defines the name of the sub-tab that appears in the _Example_ module's tab. Replace `UI` with the text you want to appear as the sub-tab title. + - `page arguments`: This is the name of the directory that contains the content for the sub-tab. Replace `ui` with the name of the folder file that contains the code for your new sub-tab. + - `weight`: The weight controls the placement of the sub-tabs with respect to the others that appear. Sub-tabs with lower weights appear further left and those with higher weights appear further right. +1. Create a folder for the sub-tab that you named in the `page arguments` above. +1. Create a `.html` file using the same base name as the folder (e.g. `abc.html`). +1. Insert some _dummy code_ into the `.html` file for now just to get the sub-tab up and visible. For example: + ```html +

This is my sub-tab

+ ``` + - Note that it is not necessary to include all of the html elements (e.g. ``, ``, `` etc). The code that you provide in this file is inserted into the body of the page when it is generated by Drupal. +1. Clear the Drupal cache: + - `docker exec -it fd2_farmdata2 drush cc all` +1. Visit the FarmData2 home page when logged in as a _Farm Worker_, a _Farm Manager_ or as `admin`. Your new sub-tab should now be visible under the _FD2 Example_ tab. You can find the login credentials that are available in the developement environment on the [INSTALL.md](https://github.com/DickinsonCollege/FarmData2/blob/main/INSTALL.md) page. + - If your tab does not appear, there are likely syntax errors in the `fd2_example.module` file or in your `.html` file. You can log into FarmData2 as `admin` and check the Drupal error logs on the `admin/reports` page. +1. Replace the _dummy code_ in your `.html` file with the code for your new sub-tab. This file can contain any valid html code including CSS, JavaScript, Vue.js, etc... + - Sub-tabs typically (e.g. `ui.html`) use Vue.js, Axios and the FarmOS API to interact with the FarmData2 database. More information on these tools and resources for getting started with them are available in the [ONBOARDING.md](https://github.com/DickinsonCollege/FarmData2/blob/main/ONBOARDING.md) file. + +#### Local JavaScript and CSS Libraries #### + +Local libraries, such as those in the `fd2_tabs/resources` directory, are included by adding them to the `.info` configuration file of the `fd2_config` module (i.e. `fd2_config/fd2_config.info`). A file added to the `fd2_config` module will be availble to all other modules. + +#### Remote or CDN Libraries #### + +Libraries such as those served from Content Delivery Networks (CDN) are included by adding them to the `_preprocess_page()` function in the `.module` file. For example, in the `fd2_example.module` file the following lines add the Vue.js and Axios libraries: +```php +drupal_add_js('https://unpkg.com/vue/dist/vue.min.js','external'); +drupal_add_js('https://unpkg.com/axios/dist/axios.min.js','external'); +``` + +The lines for external libraries must be included in each module's `.module` file. + +### Pre-defined Module Variables ### + +Drupal Modules can pass variables from the farmOS/Drupal system through to the sub-tab. All of the current modules define two such variables: + - `fd2UserID`: The numeric id of the user that is currently logged in to FarmData2. + - `fd2UserName`: The text user name of the user that is currently logged in to FarmData2. + +These variables are global and can be used in scripts and in the Vue instance within the page. Additional variables can be added to a module by adding their definitions to the `_preprocess_page()` method in the appropriate `.module` file. See the `fd2_example_preprocess_page()` function in the `fd2_example.module` file for an example. + +## Vue Components ## + +Vue Components help to reduce code duplication, speed up development, and create a consistent look and feel across all of the sub-tabs in FarmData2. Information about the creation of Vue Components is available in the [ONBOARDING.md](https://github.com/DickinsonCollege/FarmData2/blob/main/ONBOARDING.md) file. + +Custom Vue Components used in FarmData2 are contained in the `fd2_tabs/resources` folder. Each component is defined in a `.js` file. The filename for components should match `*Component.js` (e.g. `dropdownWithAllComponent.js`) Each component is also accompanied by a file with a name of the same prefx but with the suffix `.spec.comp.js` that contains Cypress component tests for the component (e.g. `dropdownWithAllComponent.spec.comp.js`). See below for more information on the component tests. + +### Creating Vue Components ### + +In addition to the standard implementation of a Vue Component as a JavaScript object (see `DropdownWithAllComponent.js`) each Vue Component for FarmData2 exports the object as a [CommonJS Module](https://flaviocopes.com/commonjs/) so that it can be imported into the Cypress Component test framework. For example, the snippet of code below appears at the bottom of the `DropdownWithAllComponent.js` file to export the `DropdownWithAllComponent`. + +```JavaScript +try { + module.exports = { + DropdownWithAllComponent + } +} +catch {} +``` + +- More Details: Drupal 7 adds JavaScript files to a page using a `