Welcome. We are thrilled that you are interested in contributing to FarmData2. This document contains all the information that you need to get started.
If you are new to Open Source contribution, this document is ordered top-to-bottom to provide what you need to know to begin contributing to FarmData2. Following along in order and exploring the links that it contains would be a good way to start.
If you are an experienced Open Source contributor, you might just skim this document and then jump in by:
- installing the FarmData2 Development Environment.
- reviewing the Overview of the FarmData2 Codebase.
- becoming familiar with the FarmData2 Contribution Workflow.
- referring to the FarmData2 Documentation as necessary.
We welcome different types of contributions:
- Documentation: Improve the documentation in any way - from fixing typos and grammar to revising existing documentation for correctness and clarity, to adding new documentation to help others.
- Running Tests: Run the test suite and report or confirm reported failing tests in the FarmData2 Issue Tracker.
- Issue Gardening: Help to keep the FarmData2 Issue Tracker up to date and useful by checking tickets to see if reported bugs still exist or requested improvements still make sense and then adding clarifying information to the associated issue tracker tickets.
- Bug Reporting: Work with the FarmData2 application and use the FarmData2 Issue Tracker to report any bugs you encounter.
- Improvement Suggestions: Work with the FarmData2 application and propose your ideas for how FarmData2 can be improved in the suggestions topic on the FarmData2 Zulip chat.
- Bug Fix: Make a pull request for changes to the code or tests to fix a bug reported in the FarmData2 Issue Tracker.
- New Features: Propose, discuss and provide feedback on new features in the suggestions topic on the FarmData2 Zulip chat. Then take the next step and make a pull request that implements a new feature.
- Other Ideas: If you have other ideas for contributions, propose them on the suggestions topic on the FarmData2 Zulip chat.
The following are some things that you'll need to do to get started on the path to contributing to FarmData2.
The FarmData2 community values an open, welcoming, inclusive, and harassment-free experience for all community members.
Review the Code of Conduct before engaging with the FarmData2 community.
We use a variety of licenses and agreements to guarantee that FarmData2 continues to be free and open source while protecting both the project and its community of contributors.
Review the Licensing information before contributing to FarmData2.
The FarmData2 community uses the FarmData2 Zulip chat as its primary tool for communications. It provides a place where you can search for answers and reach out to the community with questions.
The following are links to some the Zulip streams and topics that you might find useful:
- Introduce Yourself - A stream where new developers can introduce themselves to the community.
- Newcomer Questions - A topic created specifically as a place for newcomers to FarmData2 to ask questions.
- Install - A stream dedicated to questions about the installation of FarmData2.
- Developers - A stream for developers to ask questions, discuss issues and debate design decisions.
- Suggestions - A topic for discussing suggestions for changes, additions or anything related to improving FarmData2.
The Getting Started with Zulip Page from the Zulip Help Center provides a quick introduction on how to use Zulip if you want a some pointers.
FarmData2 provides a containerized Linux-based development environment with all the necessary tools and dependencies already installed. This simplifies the process of getting up and working toward your first FarmData2 contribution.
The INSTALL.md document gives descriptions and links to detailed instructions for several different approaches to installing the FarmData2 Development Environment.
With the FarmData2 Development Environment up and running, consider taking a tour of FarmData2 to familiarize yourself with what it does and how it works.
Become familiar with the organization, terminology, and tools and technologies used by FarmData2.
FarmData2 uses a modified forking workflow to accept contributions from the community. Not every contribution will be the same, but the prototypical workflow will contain the following steps.
Note that the following instructions assume that you are working within the FarmData2 Development Environment.
Peruse the Issue Tracker to find an issue on which to work:
If you are new to FarmData2, you can search the Issue Tracker for tickets with the following labels designating issues that are a good place to get started:
-
- 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, JavaScript or Bash scripting is what is necessary for addressing these issues. These issues provide a great way to get familiar with the process of making a contribution. -
- The issues described in these tickets require some understanding of FarmData2 that is typically limited to one or two source files. They will often require changes that affect behavior and therefor might also require creation or modification of unit, component or end-to-end tests. Thus, a deeper knowledge of Javascript, Vue.js, and Cypress tests will be necessary. These issues provide a great way to dig a little deeper, though still without requiring too deep a knowledge of the project.
If you have an idea that is not already in the Issue Tracker, open an issue or propose it in the suggestions topic on the FarmData2 Zulip chat:
When you find an issue that you want to work on, make a comment on the ticket expressing your interest. Use a comment such as the following:
I would like to work on this issue.If the issue is not assigned, or if it has been dormant for a while, one of the project maintainers will assign the ticket to you.
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.
New work in FarmData2 occurs on the development branch. Before beginning to address an issue you should synchronize the development branch of your local repository and your origin repository (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.
Open a Terminal window and use the following commands:
cd FarmData2
git pull --ff-only upstream development
git push origin developmentIf you cloned your FarmData2 repository somewhere other than the FarmData2 directory in the fd2dev home directory you'll need to adjust the cd command that you use.
Note that all future sections of this document will assume that the directory containing your FarmData2 repository is the current working directory.
The changes that you want to contribute must be in a feature branch.
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.
git switch development
git branch MyFeatureBranch
git switch MyFeatureBranch
git statusThe output of the git status command should confirm that you have created and switched to your new feature branch.
Open the VSCodium IDE and edit the contents of the files in your local FarmData2 repository to address the issue.
If your work requires more than one change you should iterate between this step and the following step until you fully solve the issue.
Depending upon what you are working on, one of the following guides might be helpful:
- Working on a Vue.js Component or Example
- Working on Documentation
- Working on an Entry Point
- Working on Infrastructure
- Working on a Library
Each time you complete a nameable unit of work (for example a function, a test, or adding a form element) commit the changes to your feature branch. Use a commit message for your commit that will help you identify it if you need to roll back to that commit later.
git stage <files>
git commit -m "message that describes the changes"When you make your commit, a pre-commit git hook in the FarmData2 Development Environment will run and perform a set of checks on the files that you are committing.
These checks include things such as:
- Checking code for:
- Proper formatting
- Spelling errors
- Linting issues (common coding or stylistic mistakes)
- Correctness (new and existing tests for staged files must pass)
- Checking documentation for:
- Spelling errors
- Broken links
- Use of inclusive language
If any of the pre-commit checks fail, the reasons for the failure will be displayed and the commit will not be made.
If a commit fails you will need to:
- Address the reason for the failure.
- Stage any files that you modified in addressing the failure.
- Try the commit again.
Push your feature branch to your origin repository on GitHub. Be sure to replace the text MyFeatureBranch with the name of your feature branch.
git push origin MyFeatureBranchAt this point you might:
- go back to Step #5 and add more changes to your feature branch.
- continue to the next step and create a draft pull request to let the maintainers know what you are working on and get some preliminary feedback.
- go to step Step #10 and then step Step #11 to let the maintainers know your pull request is ready for them to review and consider merging it.
As you are working on your change you can create a draft pull request. Creating a draft pull request lets the maintainers know you are working on an issue. It makes your work visible to them, but also makes it clear that your pull request is still a work in progress and not ready for a full review. Draft pull requests are a great way to begin a discussion about what you are doing and get some feedback on your work.
To create a draft pull request:
- Visit your fork of FarmData2 (your
origin) on GitHub - Create the draft pull request for your feature branch.
- When following the linked directions be sure to use:
- the
upstreamFarmData2 repository as the "base repository" developmentas the "base branch"- your
originas the "head repository" - your feature branch as the "compare branch"
- the
- When following the linked directions be sure to use:
When you create a pull request for FarmData2 you will need to include:
-
Title - a concise summary of the pull request.
-
Description - a longer description of the changes you made. This should include:
- why you made the changes.
- your approach to implementation.
- any possible complications caused by your changes.
- thoughts or questions you have for the maintainers.
- steps that a reviewer should take to review your changes.
-
Closes tags - if your pull request closes any issues, list them here by including one "Closes" tag for each issue that is closed. Include a blank line before your first
Closestag. Do not include any blank lines betweenClosestags if you use more than one. For example:Closes #123
-
Coauthor footers - if you have any coauthors, list them at the bottom of your pull request by including one "Co-authored-by line" for each coauthor. Include a blank line before your first coauthor footer, and no blank lines between coauthor footers if you have more than one. You can use this nifty little tool to generate your coauthor footers.
Co-authored-by: Awesome Contributor <[email protected]>
If your pull request is ready for review, go to the next step.
Otherwise, go back to Step #5 and continue working on your changes. But, be sure to check your draft pull request frequently for comments, feedback or questions from the maintainers and respond to them.
The development branch might have had new commits added to it since you began your work. These changes might conflict with your changes. To resolve any conflicts you should merge the current development branch into your feature branch and resolve any merge conflicts.
git switch development
git pull --ff-only upstream development
git push origin development
git switch MyFeatureBranch
git merge development
<Resolve Any Merge Conflicts>
git push origin MyFeatureBranchWhen you think you have finished your changes and are ready to have the maintainers review them mark your pull request as ready for review
Maintainer will review (or assign reviewers) and then take one of three actions
- If everything looks good, they will merge your changes into the
developmentbranch. - If they have questions or want to see further changes they will comment on the pull request and mark it as a draft pull request again. In this case you will want to review the feedback and respond to it in the comments or by making more changes (Step #5 and Step #6) and pushing them (Step #7) to update your pull request.
- If the maintainers determine that your pull request is not suitable for merging into development (even with changes), they will close the pull request with a comment explaining their decision.
Review your pull request for comments, feedback or questions from the maintainers and respond to them. This might require you to make more changes (Step #5 and Step #6) and to push them (Step #7) to update your pull request. When your pull request has addressed all the changes requested by the maintainers, merge the development branch again (Step #10) and mark your pull request as ready for review (Step #11)