Giter Site home page Giter Site logo

farmos.org's Introduction

farmOS

Licence Release Last commit Docker Chat Backers on Open Collective Sponsors on Open Collective

farmOS is a web-based application for farm management, planning, and record keeping. It is developed by a community of volunteers and aims to provide a standard platform for farmers, developers, and researchers to build upon.

Official website: farmOS.org

GETTING STARTED

If you would like to install and host farmOS yourself, see the official documentation on farmOS.org: https://farmOS.org/hosting/install

If you would like to pay for hosting, Farmier provides affordable options for individual farms and organizations.

MAINTAINERS

Current maintainers:

This project has been sponsored by:

CONTRIBUTORS

This project exists thanks to all the people who contribute.

OPENCOLLECTIVE BACKERS

Thank you to all our OpenCollective backers! [Become a backer]

OPENCOLLECTIVE SPONSORS

Support this project by becoming an OpenCollective sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

farmos.org's People

Contributors

dependabot[bot] avatar jgaehring avatar mstenta avatar paul121 avatar symbioquine avatar wotnak avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar

Forkers

jgaehring paul121 symbioquine mstenta wotnak fosten

farmos.org's Issues

Use some better tooling for linting and code correctness

I've never set up anything deliberately for linting or other tooling in this project, just using what came out-of-the-box with the Gatsby starter I used. So it's pretty lousy in the editor for detecting even the simplest issues, like undefined variables.

Switch to non-Google analytics service

I noticed another website using Simple Analytics today, and not for the first time:
https://www.simpleanalytics.com/

With the changes for #48 still fresh in my mind, I figured it would be a good time at least open an issue for this, b/c I know we've discussed it before and it seems like switching to Simple or something similar would be a no-brainer for our community. It's not something I know a ton about, however, so I would defer to others w/ more experience.

I did a quick look for Gatsby plugins, too, and I really like this one:
https://github.com/DavidWells/analytics/tree/master/packages/gatsby-plugin-analytics

I haven't dug deep, but I like the look of it b/c it's a fairly thin plugin wrapper around a well-maintained, framework-agnostic library for any analytics service you could imagine:
https://getanalytics.io/

Really nice docs!

Glossary of terms

Add a "Glossary of terms" to farmOS.org that can be used for reference to understand the terminology used throughout the system.

Link to farmOS demo site

As shared here on the forum I've created a site for building demos of farmOS: https://farmos.discourse.group/t/farmos-demo-site/1170 It's been live for almost a month now and has had at least 1 demo created each day. There were a few bugs in the beginning but they have been fixed so it seems to be running better now.

Opening this issue to propose adding a link to the demo site on farmOS.org and collect any blockers/ideas/improvements we should consider before doing so. Perhaps we could also talk about this on the April 13 monthly call
Screenshot from 2022-04-05 14-21-13

Update this project's README

As I mentioned in #17, I need at least some documentation for how this aggregates the docs from source repositories, plus some general info regarding farmos.org, maybe a link to some of the discussions around this redesign on the forum, etc.

Persist the nav drawer’s open state across page transitions

I'm punting on this for now, but it would be good to work on how the nav drawer closes after you click on one of its links.

As I mentioned on the forum:

From there I resumed work trying to figure out how to make the navigation drawer stay open, or at least close more gracefully, on page transitions. This opened up a whole can of worms regarding how the navigation is structured, such as how the navigation of a particular project’s documentation relates to the overall navigation for the site in general. Right now, it’s hard to to really anticipate what this should look like, since it won’t really be an issue until we’re using more than one source repository. But there are unavoidable knock-on effects which seem important to consider now, namely how do we aggregate and structure the data from the source repositories and parcel out portions of that data to the pages that need it. I’ve got a WIP branch started, but I’m probably going to shelve that for now, so I don’t have to deal with that can of worms just yet.

There are a lot of hairy details in this, but I'll definitely need to add a gatsby-browser.js file, and I probably want to consolidate some of the configuration for the source repos in gatsby-config.js, and streamline how that config is queried in gatsby-node.js. I may be able to resolve this w/o totally overhauling everything, so I might revisit it sooner than later, just not going to let myself get bogged down or blocked by this before putting this into production.

Trigger builds only for repos in the farmOS organization

Just occurred to me as I was mentioning compute resources in #5, I don't have to worry about forks triggering a build, since they presumably won't have the secret token, but it would be better to just disable the workflow for those cases, rather than letting them fail. Hopefully it's simple enough and can be added to farmOS/farmOS#456.

Anchor links point to the wrong location

Not sure this is the right place for this, sorry if it is not.

The anchor links (links referring to the same page) in farmOS.org don't seem to be working correctly. For example on the migration page https://farmos.org/hosting/migration/ the link to "limitations" points back to the main page. https://farmos.org/#limitations. The markdown in the documentation looks right with my limited knowledge so the problem probably lies where it is getting converted to html.

Render a link to source repo

Currently farmOS.js / farmOS.py and even farmOS don't have a link back to their respective github repos. They could add it themselves, but perhaps it would be better to add a nice little Github icon + link in this repo itself. Ideally we could pull the url from the source repo config?

farmOS Guide Menu View

The view of the menu on the left hand side on the farmOS guide page is not working correctly. The down arrows are in front of the text and the words are long and you need to scroll left and right to see the whole word in the menu.

I am using Chrome on a MacBook Pro.

Screen Shot 2023-10-17 at 9 41 36 AM
Screen Shot 2023-10-17 at 9 42 46 AM

Standardize workflow for creating demo videos

farmOS.org includes a number of screencast recordings that demonstrate specific features of farmOS. As the system continues to grow and evolve, it would be helpful to have a standardized workflow around creating/updating these videos.

I started a "demos" branch in the repository to begin exploring this. It includes a README.md file that describes a potential workflow/process.

Support for embedded MP4s

I was trying to embed MP4 files in a blog post PR (farmOS/farmOS-community-blog#16) and had trouble getting it to work. That PR is against the farmOS-community-blog repo, not this one, but this repository is responsible for converting those blogs posts into HTML files, so I think this is the right place for this issue.

I first attempted to embed the MP4 in the same way we embed images, like:

![Demo of Birth quick form](./birth.mp4)

... but that caused a build error:

3:24:23 PM: error Failed to retrieve metadata from image /opt/build/repo/farmOS.org/.cache/gatsby-source-git/blog/posts/2023/birth-quick-form/birth.mp4
3:24:23 PM: 
3:24:23 PM: 
3:24:23 PM:   Error: Input buffer contains unsupported image format

Full log: https://app.netlify.com/sites/farmos-community-blog-preview/deploys/646286a3eb759b0008fb9494

Then I tried with a <video> tag:

<video control>
  <source src="./birth.mp4" type="video/mp4">
</video>

... that went through the build process successfully, but MP4 file itself is not being copied into the build output, so it results in a 404 on the MP4 files and a blank area in the blog post where they would have been embedded.

Do we need to add a Gatsby.js plugin, or configure something differently, to make this possible?

Use Front Matter blocks for page meta and other info

I've talked a little on the forum, in issue #13 and elsewhere about this need. Basically, Front Matter is supported out of the box with gatsby-transformer-remark, which I have already installed and am using to transform all our markdown into pages. It's really a matter of deciding on some consistent variables (as I've said elsewhere, I think title, date and slug are good variables to start with), add those variables to the GraphQL queries in the template and the createPages hook, and finally use those variables them for generating paths, rendering layouts, adding SEO metadata, etc.

Fix relative links in markdown href's

There's an issue in my gatsby-remark-prefix-relative-links plugin that is causing markdown, such as

[API reference](api.md).

to be rendered as

<a href="/docs/jsapi.md/">API reference</a>

instead of

<a href="/docs/js/api/">API reference</a>

I believe this is because in the href's in farmOS.js, I'm not using a leading /, whereas href's in the farmOS repo are including a leading /:

[Entity types](/development/module/entities)

Omitting the trailing slash allows links to work with GitHub previews for farmOS.js, whereas previews for farmOS just lead to GitHub's 404 page. Ideally, both these would work, as was my original intention with gatsby-remark-prefix-relative-links. But I guess I need to make sure that intermediary / is being added in all cases. I'll need to make sure the .md gets trimmed, too.

Netlify builds failing to pull git sources from cache

I'm seeing this issue again, which I first mentioned in #8 (comment). From the Netlify logs:

12:32:19 PM: error fatal: No remote configured to list refs from.
12:32:19 PM: 
12:32:19 PM: 
12:32:19 PM:   Error: fatal: No remote configured to list refs from.
12:32:19 PM:   
12:32:19 PM:   - promise.js:90 toError
12:32:19 PM:     [repo]/[simple-git]/promise.js:90:14
12:32:19 PM:   
12:32:19 PM:   - promise.js:61 
12:32:19 PM:     [repo]/[simple-git]/promise.js:61:36
12:32:19 PM:   
12:32:19 PM:   - git.js:725 Git.<anonymous>
12:32:19 PM:     [repo]/[simple-git]/src/git.js:725:18
12:32:19 PM:   
12:32:19 PM:   - git.js:1475 Function.Git.fail
12:32:19 PM:     [repo]/[simple-git]/src/git.js:1475:18
12:32:19 PM:   
12:32:19 PM:   - git.js:1433 fail
12:32:19 PM:     [repo]/[simple-git]/src/git.js:1433:20
12:32:19 PM:   
12:32:19 PM:   - git.js:1442 
12:32:19 PM:     [repo]/[simple-git]/src/git.js:1442:16
12:32:19 PM:   
12:32:19 PM:   - task_queues.js:97 processTicksAndRejections
12:32:19 PM:     internal/process/task_queues.js:97:5

I believe this is the same as stevetweeddale/gatsby-source-git#24, and the workaround suggested there seems to do no harm at least if I run it locally, so I will try it out in production when I merge c165e24. 🤞

Hosting options (why we're using Netlify)

I'm opening (and will promptly close) this issue just to document some of the decision process in using the Netlify "starter" plan to host this, at least for the time being.

The current version of farmos.org uses GitHub pages, so the question has come up a few times, as with Field Kit (farmOS/field-kit#326 (comment)), whether we risk additional charges if we exceed Netlify's limits on traffic and build capacity for the starter tier, and how that compares to GitHub pages. So here's the breakdown, as of 2021-11-15:

GitHub Pages Netlify Starter Plan
Bandwidth 100GB per month 100GB /month (then $20 per 100)
Build limits 10 builds per hour 300 minutes /month (then $7 per 500)

They're pretty evenly matched, at least on those terms, although Netlify comes with a boatload of other free features that GHP doesn't even approach. And as I mentioned in a separate chat, perhaps the greatest advantage of Netlify is they at least give you the option of a higher price tier, if we're ever so fortunate to have that problem, while GitHub only has this advice:

If your site exceeds these usage quotas, we may not be able to serve your site, or you may receive a polite email from GitHub Support suggesting strategies for reducing your site's impact on our servers, including putting a third-party content distribution network (CDN) in front of your site, making use of other GitHub features such as releases, or moving to a different hosting service that might better fit your needs.

Soooo, yea, to me this is a no brainer, but it's helpful to have the breakdown here for future reference in case it comes up again.

Improve the main nav `:hover` styles

Right now the way the main nav is nested makes the :hover styles look a little weird, since the nested list items are indented and the background that darkens on hover doesn't extend past that indentation.

This should be a relatively easy fix, and nice to knock out sooner rather than later, definitely before adopting this for https://docs.farmos.org.

Update to Gatsby 5

Issue #75 revealed that some newer Gatsby plugins we want to use require Gatsby 5. We are currently on Gatsby 3.

I tried diving into this to see how hard it might be, and found that the gatsby-material-ui-components package (which is a dependency of gatsby-theme-material-ui) only supports Gatsby 3 or 4, but not 5: https://github.com/hupe1980/gatsby-theme-material-ui/blob/3dab8327c7f6f9d32adf3fa78127316a00f562eb/packages/gatsby-material-ui-components/package.json#L27

gatsby-theme-material-ui hasn't been updated since August 2022, so I wonder if it's no longer maintained? What does that mean for farmOS.org?

Add maintainer bios

Spun this off as a follow-up issue from #23. Might make sense to draft this all together as a unified PR, so we can merge it all at once.

Add search

Adding search is probably a little too involved to consider it a stretch goal, at least prior to putting this site into production. It would be really nice to have, though, and should be prioritized before getting too far into rebranding or other advanced features.

There is an excellent guide in the Gatsby docs, "Adding Search".

It looks like the MkDocs search plugin uses lunr.js under the hood. One of the Gatsby plugins recommended in the "Adding Search" guide uses elasticlunr, so it might be a good option.

Add another source repo

I don't know if this should be a "must-have" prior to deployment, since it's not strictly necessary, but would cement this as a proof-of-concept to demonstrate how the architecture works with multiple source repos.

As I mentioned on the forum and in #7:

This opened up a whole can of worms regarding how the navigation is structured, such as how the navigation of a particular project’s documentation relates to the overall navigation for the site in general. Right now, it’s hard to to really anticipate what this should look like, since it won’t really be an issue until we’re using more than one source repository.

So I guess this depends on two other related issues, both of which are quite substantial.

First is how to structure the navigation data (eg, nav in mkdocs.yml) and how that gets handled as a GraphQL node in Gatsby. This can be done right now, but I think there are some major changes I could make so this is easier to do for each source repo we want to add. As I also mentioned in #7:

There are a lot of hairy details in this, but I'll definitely need to add a gatsby-browser.js file, and I probably want to consolidate some of the configuration for the source repos in gatsby-config.js, and streamline how that config is queried in gatsby-node.js. I may be able to resolve this w/o totally overhauling everything, so I might revisit it sooner than later, just not going to let myself get bogged down or blocked by this before putting this into production.

Second is the impact on the UI itself. Right now, the page layout is still structured for a single source of documentation, so we'll have to rethink how to allow navigation between different docs, what to use as a homepage, etc, etc. Part and parcel of that is issue #1. There's also the aspect of the sitemap itself, as I mentioned way back in May on the forum:

Basically, I'm thinking about the ultimate configuration, when this becomes farmos.org, how do we breakdown the paths to the different projects' documentation?

  • One option...
    • farmos.org/docs/farmos/
    • farmos.org/docs/field-kit/
    • farmos.org/user-guide/farmos/
  • Another option...
    • farmos.org/farmos/docs/
    • farmos.org/farmos/user-guide/
    • farmos.org/field-kit/docs/
    • farmos.org/field-kit/user-guide/
  • And yet another...
    • farmos.org/docs/ (main farmOS docs)
    • farmos.org/user-guide/ (main farmOS user guide)
    • farmos.org/field-kit/docs/
    • farmos.org/field-kit/user-guide/
  • etc.

I could go on ad nauseam. Lots of options, probably necessitating a larger discussion, and some passage of time to see how the rest of the redesign shakes out.

So yea, many more issues fall out from this one as soon as you start tugging at the threads. But none of them are intractable, imo. I think most of them boil down to lots of decisions that need to be made, but the implementation should be pretty straightforward after that. It will simply take some conversation(s) to get to that point.

Discourse integration

In the last monthly call we discussed the possibility of integrating Discourse topics with blog/tutorial posts, as a way of providing greater details, compatibility issues, and flagging tutorials that need to be updated.

Today I also came across this older issue, farmOS/farmOS.org#98, which could take a similar approach.

Trigger build hook only when the `docs/**/*` changes

Right now, any time there's a change anywhere in the farmOS repository, it will trigger the Netlify build hook for the whole site, even if there were no changes to the docs. This could pay a heavy toll in terms of unnecessary compute resources, and could end up exceeding the limits on our Netlify plan. I'm hopeful there's a straightforward way to add this to an if expression in the workflow, so I think this should be resolved before putting anything into production.

Duplicate links to the `docs/index.md` in navigation drawer

This is a side-effect arose somewhere in the course of resolving #8, possibly probably with bfae288:

image

The second "farmOS.js Docs" menu item is an unnecessary duplicate, since it's the same as the "Getting started". The docs/index.md page for farmOS is not duplicated, but it would be better if the "farmOS 2.x Docs" was instead "Introduction" or something similar.

Ultimatley, this is all more fallout from adopting mkdcos.yml as our main configuration file for this site. MkDocs doesn't require it to actually specify a title for the docs/index.md file, or even list it in the nav section, since it is assumed to be the root of the website, and the title is essentially just the site_name. This is how the farmOS mkdocs.yml is structured, but the farmOS.js config.yml` is not.

I think this might take some adjustment in different places. Obviously, the logic for the navigation drawer should be using the "Getting started" title, but it would be ideal if the farmOS mkdocs.yml specified the title of its own docs/index.md page, so we aren't reusing the "farmOS 2.x Docs" title, as we are in so many places in that above screenshot.

Documentation: Add DDEV/Composer Install Instructions

Describe the bug
It's not clear how to install farmOS using Composer from the documentation. This can be a problem when using DDEV with Colima, as the recommended Docker container approach may not work.

Recommendation
Add the following snippet to https://farmos.org/development/environment:

For certain local environments, installing farmOS by Composer may be more straightforward. The following commands would allow farmOS to be installed in a DDEV container:

mkdir farmos-ddev
cd farmos-ddev
ddev config --project-type=drupal9 --docroot=web --create-docroot
ddev start
ddev composer create "farmos/project:2.x-dev"
ddev composer require drush/drush
ddev drush si

(HT @wotnak)

Fix `h1` headers in the Table of Contents

As I first pointed out in #8 (comment), the Table of Contents for the farmOS.js docs are omitting all but the first h1 heading for each page. This is attributable to how the tableOfContents HTML is being altered in the docs template:

https://github.com/farmOS/farmos.org-EXPERIMENTAL/blob/dde4781adb1f2ff2385b60ab918988d410e9f740/src/templates/docs-page.js#L38-L53

I did this to accomodate a quirk of how the farmOS docs use h1/# more as a title than a proper heading. I knew at the time it would lead to such issues, but I used this quick fix so we could have a broader discussion when the time came.

Well, the time has come. @mstenta, what are your thoughts?

IMO, it's better to use h1 as a true, semantic heading. Markdown doesn't have syntax for titles, but now that we're using Gatsby, we can use Frontmatter for these kinds of details. I see Frontmatter as a good analog to the <head> tag, which is where the title really belongs, rather embedding it in the markup.

HTML anchor links get covered by the site header

Describe the bug

It seems that the current CSS rules result in documentation headers getting rendered underneath the green bar at the top of every page when you navigate directly to them via anchor links.

For example, when linking directly to a section of a page using an anchor link, I would expect to see that section's header, but I do not - it is hidden under the green bar.

For example: https://farmos.org/guide/#dashboard - we should see "Dashboard" when clicking that link, but instead you have to scroll back up a little to see it.

To Reproduce

Steps to reproduce the behavior:

Click this link: https://farmos.org/guide/#dashboard

Expected behavior: we should see "Dashboard" when clicking that link, but instead you have to scroll back up a little to see it.

Screenshot:

Screenshot from 2023-02-25 08-41-01

This is even more apparent when you are clicking on the links in the right sidebar to jump around between sections of a page.

For example, start here: https://farmos.org/model/type/log/

Click on any link in the right sidebar, and observe that the header of the section you clicked on is not visible at the top of the page.

Notably, if I use dev tools to delete the entire green bar <header> element from the DOM, I can see that the anchor links do in fact work... but they are at the very top of the page (normally rendered under the green bar).

Screenshot:

Screenshot from 2023-02-25 08-45-28

Handling external links

So I've been thinking about this since @paul121 opened up #21 and #22, particularly as I've shifted my thinking that links to the source repositories (not for editing docs, just for viewing source) probably fit best in the left navigation drawer. We could then add the "open-in-new" icon to those menu items, plus any other external links in the menu, like for the forum, chat and the Jitsi link. And while we're at it, it would be pretty easy to also set target="_blank" to open it in a new window as well. The easiest way to do this is probably to check if the href starts with 'http' or not. If we're doing that, we could also run other tests, like if it starts with 'https://github.com/' or 'http://twitter.com' and add a little GitHub or Twitter icon inline as well.

All this makes me think this logic should be written into the NestedNav component itself, or as a special ExternalLink component that could be used in NestedNav and elsewhere, since this seems more and more like a concern for the rendering layer.

Similarly, we could add some logic to gatsby-remark-prefix-relative-links to add a special class to external links, so we could append an ::after pseudo-element to those links with the same "open-in-new" icon, similar to how Wikipedia does with inline external links.

Separate the main navigation menu from the table of contents.

I spent a lot of time today trying to figure out how to move the Layout component into the wrapPageElement component from the Gatsby Browser API. There's a whole lot of issues with that, which I should document in another issue, but I think it would go a ways to help if I separated the table of contents from the general layout of the site as a whole, and incorporated it into the layout for the docs page itself. From a purely UI perspective, the main nav menu and ToC are closely related, since the former comprises the left margin and the latter the right margin, but they're dependent on two entirely different data sources. The main nav's data source is static, and will always remain the same at runtime, even between page transitions. But the ToC will be different for every page, and so it will need to be rerendered each time. It also means it won't need to persist its state across page transitions, which is the entire issue with the main nav's drawer staying open.

Add canonical tag to all blog posts

Blog followup (after #49 is merged) that came up on the monthly call today.

The canonical tag is added to posts that define canonical in front matter, but not to other posts. We should add canonical to all posts to avoid potential SEO issues (eg: if trailing slash is ommitted, or http vs https).

2.x Go-Live Punchlist

Here is the definitive list of tasks to going live with the new farmOS.org!

Prepare

Deploy

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.