diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1c63372..0a388a22 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,3 +44,8 @@ This way we can make sure it will not be introduced again. ## Documentation Whenever you are submitting new features make sure to also add documentation comments in the code. Please adhere to the [effective-dart](https://dart.dev/effective-dart/documentation) documentation guidelines. + +## Workflow +We use a rebase workflow, meaning that we rebase PRs onto the latest main branch instead of merging the current main into the development branches. +This helps to keep the git history cleaner and easier to bisect in the case of debugging an error. +You can read more on it [here](https://www.atlassian.com/git/tutorials/merging-vs-rebasing). \ No newline at end of file diff --git a/README.md b/README.md index 07d2d84f..533e9635 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,74 @@ -# neon +# Neon Neon logo A framework for building convergent cross-platform Nextcloud clients using Flutter. -## Features +## The goals of Neon -See [here](packages/app/README.md) for screenshots. +The Neon project has three main goals: -- :heavy_check_mark: Supported -- :rocket: Planned - -| App | Status | -|---------------|--------------------| -| Files | :heavy_check_mark: | -| News | :heavy_check_mark: | -| Notes | :heavy_check_mark: | -| Notifications | :heavy_check_mark: | -| Activity | :rocket: | -| Calendar | :rocket: | -| Contacts | :rocket: | -| Cookbook | :rocket: | -| Dashboard | :rocket: | -| Photos | :rocket: | -| Talk | :rocket: | -| Tasks | :rocket: | - -## Problems with other clients and how this project tries to solve them +1. The [Neon framwork](packages/neon/neon/) does the heavy lifting for Nextcloud client developers. Neon already handles the authentication flow and manages data requests and caching. This means that developers can reuse a lot of the code and do not need to reinvent the wheel. +2. The [Neon app](packages/app/) is a cross platform Nextcloud client that runs on iOS, Android, macOS, Windows, Linux and Web. We already support Android and Linux with the other platforms being work in progress. +3. The [Neon app](packages/app/) is a multi client app. This means that you can have multiple clients in the same mobile app. It enables seamless switching between multiple apps as Nextcloud users have enjoyed on the web forever. ### Current problems with other clients -_Excerpt from my job application to Nextcloud:_ - - There are many clients that are designed to run exclusively on a single platform or device type. They all have different code bases, which makes feature parity and maintenance much more difficult. -- The user experience and features differ significantly from platform to platform, which leads to frustration. This particularly affects mobile devices running Linux (e.g. postmarketOS). There is no suitable client on this platform at all. Using the desktop Linux client for file synchronization would probably work, but this platform still lacks almost all the features available on e.g. Android and the client is not made for mobile screens. Someone who uses Linux on their mobile device is likely also interested in Nextcloud, so the need for a solution is definitely there. -- Even on feature-rich platforms, features are spread across multiple apps (e.g. on Android), making it more complicated for the user who simply wants to get the most out of their Nextcloud server on their device. +- The user experience and features differ significantly from platform to platform, which leads to frustration. This particularly affects mobile devices running Linux (e.g. postmarketOS). There is no suitable client on this platform at all. Using the desktop Linux client for file synchronization would probably work, but it still lacks almost all the features available on e.g. Android and the client is not converging to the needs of a mobile screens. +- Even on feature-rich platforms, features are spread across multiple apps, making it more complicated for the user who simply wants to get the most out of their Nextcloud server on their device. ### How Neon as a framework tries to solve them -This project uses OpenAPI specifications to generate all the necessary API client code. -This vastly reduces the developer efforts of writing a lot of boilerplate code and having to look at the PHP source code. -Most server APIs were not well or at all documented until now (there are some exceptions). -Based on this work a project at the Nextcloud company started for adopting OpenAPI to document the server APIs. -The OpenAPI specifications are generated completely automated from the source code (although some changes to the type annotations are required) and are validated with static analysis of the PHP code. -These efforts are not done yet, but this project basically became the front-line for testing the automatically generated specifications. +The Neon project uses [Dart](https://dart.dev/) and [Flutter](https://flutter.dev/) to help mobile client developers building apps. Flutter allows us to build convergent cross platform clients that feel native. +We are a 100% FOSS framework and do not rely on any proprietary libraries making it easy for developers to publish thier apps in places like the [F-Droid](https://f-droid.org/) store. +We provide a generated [Nextcloud Dart client](packages/nextcloud/) that is generated from the new OpenAPI specifications shipped with Nextcloud and is already being used by other Dart and Flutter projects. Gone are the days of looking at the PHP code and implementing an API client by hand wich can be time consuming and very error prone. -We use flutter because of its cross-platform capabilities. -To decrease the developer burden, a lot of useful widgets and utilities have been developed, so that they can be re-used. -Trying to make everything re-usable is a major goal of this project, as we want to close the gap between platforms and functionalities and make development of new clients and apps enjoyable and fast. -Developing a new Nextcloud client can be as easy as adding some UI and then necessary state management, everything else is taken care of for you. +We provide abstractions, common utilities and prebuilt UI components (called Widgets in Flutter) that can be re-used. This allows Neon to make developing a new Nextcloud client as easy as adding a few custom UI elements and the necessary state management, while everything else is already taken care of for you. ## Contributing -Checkout our [contributing docs](CONTRIBUTING.md) to get started with developing with Neon. +We encourage every client developer to contribute their app implementation back into Neon. +This way we app developers can choose from a large set of clients to enable. +Check out our [contributing docs](CONTRIBUTING.md) to get started with developing with Neon. + +We have a lot of [documentation](./docs) from helping you setup your development environment to our guidelines. +Please make sure to read them before starting to contribute. ## Development and support We have a Matrix space where you can ask questions: https://matrix.to/#/#nextcloud-neon:matrix.org -## Documentation +## Features -See [docs](./docs). +See [here](packages/app/README.md) for screenshots. -## Platform support +- :heavy_check_mark: Supported +- :construction: Work in progress +- :rocket: Planned + +| App | Status | +|-----------------------------------------------|--------------------| +| [Files](packages/neon/neon_files/README.md) | :heavy_check_mark: | +| [News](packages/neon/neon_news/README.md) | :heavy_check_mark: | +| [Notes](packages/neon/neon_notes/README.md) | :heavy_check_mark: | +| Notifications | :heavy_check_mark: | +| Activity | :rocket: | +| Calendar | :rocket: | +| Contacts | :rocket: | +| Cookbook | :rocket: | +| Dashboard | :rocket: | +| Photos | :rocket: | +| Talk | :rocket: | +| Tasks | :rocket: | -Except for web, Neon should run on all supported Flutter platforms in the future. -Right now this is not the case, only Android and Linux are supported and tested, but this can easily be extended to other platforms. +## Platform support -The features and problems of all platforms should be considered when implementing new features. +| Platform | Progress | +|-----------|--------------------| +| Android | :heavy_check_mark: | +| iOS | :construction: | +| MacOS | :construction: | +| Linux | :heavy_check_mark: | +| Windows | :rocket: | +| Web | :construction: | diff --git a/docs/README.md b/docs/README.md index d99e4c8d..b4201d4c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,25 @@ # Documentation -## [Code of Conduct](../CODE_OF_CONDUCT.md) +## Terminology +There can be a lot of confusion what an `app` is. It can mean a server app conventionally written in PHP, the app implementation of one or a mobile app built with Neon. +Therefore we use the following naming: +- **App** as the resulting user facing app that enables one or more clients +- **Client** for the implementation of a server PHP app +- **API-Client** as the Dart client generated from the OpenAPI specifications +- **Server app** as the app running on the server conventionally built with PHP +- **Neon project** is this entire mono repository containing all the code +- **Neon framework** the Flutter Nextcloud app framework itself -## [Contributing](../CONTRIBUTING.md) +## Code of Conduct +Please read the [Code of Conduct](../CODE_OF_CONDUCT.md). This document offers some guidance to ensure Nextcloud and Neon participants can cooperate effectively in a positive and inspiring atmosphere, and to explain how together we can strengthen and support each other. -## [Architecture overview](architecture.md) +## Contributing +Please review the [guidelines for contributing](../CONTRIBUTING.md) to this repository to help you get started with our workflows and tools. + +## Architecture overview +Check out our little [overview](architecture.md) of how the Neon project is built to help you get started. ## [Login user flow](login.md) + +## [Neon workflows](workflows.md) +We have documented various workflows for working with the mono repo structure like adding a new package. \ No newline at end of file diff --git a/docs/architecture.md b/docs/architecture.md index 7228791b..f040dee9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,8 +2,9 @@ ![Architecture overview diagram](architecture.svg) -The framework consists of multiple packages: -- For APIs the nextcloud package provides the implementations. The dynamite generator generates the code using the OpenAPI specs. -- The main package is the neon package that provides widgets and functionality that is useful for building a Nextcloud client. It also manages the global state at runtime so that the app implementations do not have to manage things like multiple accounts for example. -- The individual apps are implemented as separate packages. Those depend on the neon framework and implement a few interfaces so that the neon framework can use them. -- On top of all that sits the app package that injects the relevant app implementations into the framework. It is possible to configure which app implementations should be included and how the app is branded. +The Neon project consists of multiple packages: +- The `nextcloud` package provides implementations for multiple server APIs. These are generated with the `dynamite` generator utilizing the OpenAPI specifications shipping since Nextcloud Hub 6. +- Plugins are special clients that are deeper implemented into the framework and need to be closely coupled with it. +- The individual clients are implemented as separate packages. These depend on the Neon framework and implement a few common interfaces so they can be used together in apps. +- The main star is the `neon` package that provides common UI components (Widgets) and functionality that is useful for building Nextcloud apps. It also manages the global state at runtime so clients do not have to manage multiple accounts, data fetching or caching. +- On top of all that sits the app package that injects a set of selected clients into the framework. It is possible to configure which one should be included and add custom styling and branding to it. diff --git a/docs/architecture.puml b/docs/architecture.puml index c059b2c5..34c39506 100644 --- a/docs/architecture.puml +++ b/docs/architecture.puml @@ -1,6 +1,6 @@ @startuml architecture -package "neon framework" { +package "Neon framework" { component neon component nextcloud component settings @@ -8,7 +8,7 @@ package "neon framework" { component file_icons } -package "App implementations" { +package "Clients" { component neon_files component neon_news component neon_notes @@ -17,7 +17,7 @@ package "App implementations" { package "OpenAPI" { component dynamite - component specs + component specifications } component app @@ -34,11 +34,10 @@ neon_notifications --> neon neon --> nextcloud -neon --> settings neon --> sort_box neon --> file_icons dynamite --> nextcloud -specs --> nextcloud +specifications --> nextcloud @enduml \ No newline at end of file diff --git a/docs/architecture.svg b/docs/architecture.svg index 17f6d5a4..1b90c7e9 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -1 +1 @@ -neon frameworkApp implementationsOpenAPIneonnextcloudsettingssort_boxfile_iconsneon_filesneon_newsneon_notesneon_notificationsdynamitespecsapp \ No newline at end of file +Neon frameworkClientsOpenAPIneonnextcloudsettingssort_boxfile_iconsneon_filesneon_newsneon_notesneon_notificationsdynamitespecificationsapp \ No newline at end of file diff --git a/docs/workflows.md b/docs/workflows.md new file mode 100644 index 00000000..b398aabf --- /dev/null +++ b/docs/workflows.md @@ -0,0 +1,10 @@ +# Workflows + +## Adding a new package to the Neon project + +If you need to add a new package to the Neon project pleae make sure to execute all the following steps: +1. Use the according template by running `fvm dart create -t package package_name` or `fvm flutter create -t package package_name`. +2. Make sure to activate our strict linting by adding it to the package. +3. Regenerate the dependency overrides by executing `melos bootstrap`. +4. Add a Symlink to our main [license](../LICENSE). +5. Update [commitlint.yaml](../commitlint.yaml) and [tool/build-app.sh](../tool/build-app.sh) by adding the new package name. \ No newline at end of file