Mirrored_Repos/AppFlowy
1
0
Fork 0
mirror of https://github.com/AppFlowy-IO/AppFlowy.git synced 2024-08-30 18:12:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #178 from MikeWallaceDev/add_linux_desktop_file

Browse Source 
Add linux desktop file
This commit is contained in:
AppFlowy.IO 2021-12-18 09:26:44 +08:00 committed by GitHub
commit cdb36f9526
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 153 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/APPFLOWY_SYSTEM_DESIGN.md
View File

@ -1,17 +1,17 @@
# 🥳 AppFlowy - Event Driven System
# 🥳 AppFlowy - Event Driven System
* Goals of the System
* Some Design Considerations
* High Level Design
* Component Design
* [Goals of the System](#goals-of-the-system)
* [Some Design Considerations](#some-design-Considerations)
* [High Level Design](#high-level-design)
* [Component Design](#component-design)
## 🎯 Goals of the System
The AppFlowy project is an attempt to build a high performance application. Here are the top-level requirements for out system.
The AppFlowy project is an attempt to build a high performance application. Here are the top-level requirements for our system.
1. **High Performance.**
1. **High Performance.**
2. **Cross-platform.**
3. **Reliability**
4. **Safety**
3. **Reliability.**
4. **Safety.**
## 🤔 Some Design Considerations
@ -41,7 +41,7 @@ The AppFlowy project is an attempt to build a high performance application. Here
│
│
```
Here are the event flow:
Here is the event flow:
1. User click on the `Widget`(The user interface) that invokes the `Bloc` actions
2. `Bloc` calls the repositories to perform additional operations to handle the actions.
3. `Repository` offers the functionalities by combining the event, defined in the `FlowySDK`.
@ -69,5 +69,3 @@ The Frontend follows the DDD design pattern, you can recap from [**here**](DOMAI
│ Repository C │────┘
└──────────────┘
```

114
doc/CONTRIBUTING.md
View File

@ -1,95 +1,76 @@
# Contributing to AppFlowy
<p align="center"><img src="imgs/appflowy_title_and_logo.png" alt="The Open Source Notion Alternative." width="500px" /></p>
Hello, and welcome! Whether you are trying to report a bug, proposing a feature request, thinking about getting involved in the project ,or submitting a patch, this document is for you! It intends to be both an entry point for newcomers to AppFlowy's community (with various backgrounds), and a guide/reference for contributors.
# Contributing to AppFlowy
Hello, and welcome! Whether you are trying to report a bug, proposing a feature request, thinking about getting involved in the project, or submitting a patch, this document is for you! It intends to be both an entry point for newcomers to AppFlowy's community (with various backgrounds), and a guide/reference for contributors.
Consult the Table of Contents below, and jump to the desired section.
## Table of Contents
- [Contributing](#contributing)
- [Non-coded Contributions](#non-coded-contributions)
- [Feedback](#feedback)
- [Non-coding Contributions](#non-coding-contributions)
- [Coding Contributions](#coding-contributions)
- [Report a Bug](#report-a-bug)
- [Helping Others](#helping-others)
- [Submit a Patch](#submit-a-patch)
- [Tell Us Your Suggestions](#tell-us)
- [Sponsor](#sponsor)
- [Sponsor](#sponsor)
- [Contributor T-shirt](#contributor-t-shirt)
- [Code of Conduct](#code-of-conduct)
- [Sign the CLA Agreement](#sign-the-cla-agreement)
## Contributing
There are many ways in which you can contribute to the project. You can be involved just a little, or a whole lot! Every lit bit helps and is very appreciated by everyone.
### Non-coded Contributions
### Feedback
There can help in multiple ways - even if you don't write code, you can still give back your love to our community. Here are a few ideas:
Not feeling quite up to working on the project yet? Tell us your suggestions!
- Submit [feature requests](https://github.com/AppFlowy-IO/appflowy/issues). We'd love to hear your ideas!
- Report [bugs](https://github.com/AppFlowy-IO/appflowy/issues). This really helps a lot!
- Provide your suggestions on the [forum](https://github.com/AppFlowy-IO/appflowy/discussions)
- Review [Pull Requests](https://github.com/AppFlowy-IO/appflowy/pulls)
- Provide feedback to [proposed features](https://github.com/AppFlowy-IO/appflowy/issues)
- Answer questions having ""General help wanted" labels on the [forum](https://github.com/AppFlowy-IO/appflowy/discussions)
- Improve the documentation (WIP)
- Submit feature requests on Github ([link](https://github.com/AppFlowy-IO/appflowy/issues))
- Submit an issue for feature requests. Please include the information listed below in the issue:
- 1~3 main use cases of the proposed feature
- what types of users can benefit from using your proposed feature
- Submit a patch to fix the issue [see this section](#submit-a-patch)
- Report bugs on Github ([link](https://github.com/AppFlowy-IO/appflowy/issues)). Please include relevant information listed below in the ticket:
- A summary of the issue
- A list of steps to reproduce the issue
- The version of AppFlowy you encountered the issue with
- Your configs (OS, mobile device, network, etc) that are relevant to your issue
- Be an AppFlowy's ambassador or evangelist! Proprietary software companies often have dedicated marketing teams to get more users, but luckily we have something better: you! Share your experience with AppFlowy! This can be anything:
- Write a life-hacks-style blog post on how you or your company use AppFlowy to get things done
- Spread the word on the media to get more people to join the community. To name a few channels, Product Hunt, Hacker Noon, Quora, Reddit, and Stack Overflow are good choices.
- Give a lightning talk at your local hackerspace on why you love AppFlowy
- Write a review of the pros and cons of similar open source apps
[Back to TOC](#table-of-contents)
### Non-coding Contributions
You want to work on the project, but you're not a developer? You can help in multiple ways - even if you don't write code! You can still give back your love to our community. Here are a few ideas:
- Answer questions having ""General help wanted" or "Technical help wanted" labels on the [forum](https://github.com/AppFlowy-IO/appflowy/discussions)
- Improve the documentation.
- Be an AppFlowy ambassador or evangelist! Proprietary software companies often have dedicated marketing teams to get more users, but luckily we have something better: you! Share your experience with AppFlowy! This can be anything:
- Write a life-hacks-style blog post on how you or your company use AppFlowy to get things done.
- Spread the word on all social media platforms to get more people to join the community. To name a few channels, Product Hunt, Hacker Noon, Quora, Reddit, and Stack Overflow are good choices.
- Give a lightning talk at your local hackerspace on why you love AppFlowy.
- Write a review of the pros and cons of similar open source apps.
[Back to TOC](#table-of-contents)
### Coding Contributions
Developers who consider participating in AppFlowy's development, please go here to start:
#### Report a Bug
Please include relevant information listed below in the ticket ([link](https://github.com/AppFlowy-IO/appflowy/issues)):
- A summary of the issue
- A list of steps to reproduce the issue
- The version of AppFlowy you encountered the issue with
- Your configs (OS, mobile device, network, etc) that are relevant to your issue
#### Helping Others
Helping other members of the community by answering questions having "Technical help wanted" or "General help wanted" labels on the [forum](https://github.com/AppFlowy-IO/appflowy/discussions)
#### Submit a Patch
We love to receive Pull Requests.
- If you are a beginner or a newcomer, here are some tasks for you to get ramped up:
- Fix a typo in code
- Fix a typo in the documentation (WIP)
- Awesome issues for beginners or newcomers (WIP)
- Provide feedback on the proposed features ([link](https://github.com/AppFlowy-IO/appflowy/issues))
- Review Pull Requests ([link](https://github.com/AppFlowy-IO/appflowy/pulls))
So you want to submit code, documentation, or graphical expertise? Welcome to the club! We will try to give you all the help you need to get up and running.
- Join our [Discord](https://discord.com/invite/9Q2xaN37tV). Here you will be able to chat with all of our contributors and the heads of the project.
- Read the documentation. You should start at the main README.md where you will find information on how to setup your computer to develop with Flutter and Rust.
- Read the technical wiki. This is where you will find all of our design documentation. (TBD)
- Submit a Patch. We love to receive Pull Requests. If you are a beginner or a newcomer, here are some tasks for you to get ramped up:
- Fix a typo in the code.
- Fix a typo in the documentation.
- Awesome issues for [beginners or newcomers](https://github.com/AppFlowy-IO/appflowy/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue+for+devs%22).
- Provide feedback [proposed features](https://github.com/AppFlowy-IO/appflowy/issues)
- Review [Pull Requests](https://github.com/AppFlowy-IO/appflowy/pulls)
- If you are ready to code (maybe a lot), please submit a [patch](https://github.com/AppFlowy-IO/appflowy/pulls)!
- (WIP: guidelines)
- (WIP: Code Style)
#### Tell Us
Not feeling quite up to contributing? Tell us your suggestions!
- Submit feature requests ([see this section](#non-coded-contributions))
- Provide your suggestions on the [forum](https://github.com/AppFlowy-IO/appflowy/discussions)
- Review Pull Requests ([link](https://github.com/AppFlowy-IO/appflowy/pulls))
- Provide feedback on the proposed features ([link](https://github.com/AppFlowy-IO/appflowy/issues))
[Back to TOC](#table-of-contents)
## Sponsor
### Sponsor
Sponsoring is another great way to contribute to the community.
- Buy us a coffee on [ko-fi](https://ko-fi.com/appflowy)
Sponsoring is another great way to contribute to the community.
- Buy us a coffee on [ko-fi](https://ko-fi.com/appflowy)
[Back to TOC](#table-of-contents)
## Contributor T-Shirt
If your Pull Request was accepted as it fixes a bug, adds functionality, or makes AppFlowy's codebase significantly easier to use or understand, congratulations! You are now an official contributor to AppFlowy. Get in touch with us ([link](https://tally.so/r/mKP5z3)) to receive the very special Contributor T-shirt!
@ -98,6 +79,7 @@ Proudly wear your T-shirt and show it to us by tagging [@appflowy](https://twitt
[Back to TOC](#table-of-contents)
## Code of Conduct
Please report a code of conduct violation to annie@appflowy.io.
@ -106,4 +88,10 @@ Let's encourage the behavior we want to see in the world and constantly foster a
[Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)
[Back to TOC](#table-of-contents)
## Sign the CLA Agreement
TBD
[Back to TOC](#table-of-contents)

61
doc/DOMAIN_DRIVEN_DESIGN.md
View File

@ -50,11 +50,11 @@ specific role and responsibility.`DDD` consists of four layers.
**Infrastructure Layer**:
* Provides generic technical capabilities that support the higher layers. It deals with APIs, persistence and network, etc.
* Implements the repository interface and hiding the complexity of the Domain layer.
* Implements the repository interface and hides the complexity of the Domain layer.
As you see, the `Complexity` and `Abstraction` of these layers are depicted in this diagram. Software system are composed in layers,
As you see, the `Complexity` and `Abstraction` of these layers are depicted in the following diagram. Software system are composed in layers,
where higher layers use the facilities provided by lower layers. Each layer provides a different abstraction from the layer above
and below it. As a developer, we should pull the complexity downwards. Simple interface and powerful implementation(Think about the
and below it. As developers, we should pull the complexity downwards. Simple interfaces and powerful implementations (Think about the
[open](https://man7.org/linux/man-pages/man2/open.2.html) function). Another way of expressing this idea is that it is more important
for a module to have a simple interface than a simple implementation.
@ -76,25 +76,21 @@ for a module to have a simple interface than a simple implementation.
### Data Model
DDD classifies data as referenceable objects, or entities, and non-referenceable objects, or value objects. Let's introduces
some terminologies from DDD.
DDD classifies data as referenceable objects, or entities, and non-referenceable objects, or value objects. Let's introduce some DDD terminology.
**Entity**
`Entities` are referenceable because they carry an identity which allows us to reference them. e.g. user, order, book, etc.
You can use `entities` to express your business model and encapsulate them into Factory that provides simple API interface
to create Entities.
`Entities` are plain objects that carry an identity which allows us to reference them. e.g. user, order, book, etc.
You use `entities` to express your business model and encapsulate them into Factory that provides a simple API to create Entities.
**Value Object**
`Value Object` can't be referenced. They can be only included into entities and serve as attributes. Value objects could be
simple and treat as immutable. e.g. email, phone number, name, etc.
`Value Object` can't be referenced. They can be only included into entities and serve as attributes. Value objects could be simple and treat as immutable. e.g. email, phone number, name, etc.
**Aggregate**
`Entity` or `Value object` can be grouped into aggregates. Aggregates can simplify the model by accessing the entire aggregate.
For instance, Table has lots of row. Each row using the table_id to reference to the
`Entities` and `Value objects` can be grouped into aggregates. Aggregates can simplify the model by accessing the entire aggregate.
For instance, Table has lots of rows. Each row using the table_id to reference to the
table. TableAggregate includes two entities: Table and the Row.
```
@ -113,10 +109,7 @@ table. TableAggregate includes two entities: Table and the Row.
**Service**
When a significant process of transformation in the domain is not a natural responsibility of an `Entity` or `Value object`, add
an operation to the model as standalone interface declared as a Service. For instance: The `Value object`, EmailAddress,
uses the function `validateEmailAddress` to verify the email address is valid or not. `Service` exists in Application, Domain and
Infrastructure.
When a significant process of transformation in the domain is not a natural responsibility of an `Entity` or `Value object`, add an operation to the model as standalone interface declared as a Service. For instance: The `Value object` EmailAddress uses the function `validateEmailAddress` to verify if the email address is valid or not. `Service` exists in Application, Domain and Infrastructure.
```
class EmailAddress {
@ -127,7 +120,7 @@ class EmailAddress {
validateEmailAddress(input),
);
}
const EmailAddress._(this.value);
}
@ -139,9 +132,12 @@ Either<Failure<String>, String> validateEmailAddress(String? input) {
**Repository**
Repository offer an interface to retrieve and persist aggregates and entities. They hide the database or network details from the domain.
The Repository interfaces are declared in the Domain Layer, but the repositories themselves are implemented in the Infrastructure Layer.
You can replace the interface implementation without impacting the domain layer. For instance:
Repositories offer an interface to retrieve and persist aggregates and entities. They hide the database or network details from the domain.
Repository interfaces are declared in the Domain Layer, but the repositories themselves are implemented in the Infrastructure Layer.
You can replace the interface implementation without impacting the domain layer.
For instance:
```
// Interface:
@ -161,7 +157,7 @@ The diagram below is a navigational map. It shows the patterns that form the bui
![[image from here](http://uniknow.github.io/AgileDev/site/0.1.8-SNAPSHOT/parent/ddd/core/building_blocks_ddd.html)](imgs/domain_model_relation.png)
## 🔥 Operation Flow
## Operation Flow
```
@ -194,9 +190,7 @@ interaction │ │ └──────▲────────
```
1. Widget accepts user interaction and transfers the interactions into specific events. The events will be send to the Application layer,
handled by the specific `bloc`. The `bloc` send the states changed by the events back to the widget, and finally the `Widget` update
the UI according to the state. The pattern is depicted in this diagram. (More about the flutter [bloc](https://bloclibrary.dev/#/coreconcepts?id=bloc))
1. Widget accepts user interaction and translates the interactions into specific Events. The events will be sent to the Application layer, handled by the specific `bloc`. The `bloc` sends the states changed by the events back to the widget, and finally the `Widget` updates the UI according to the state. The pattern is depicted in this diagram. (More about the flutter [bloc](https://bloclibrary.dev/#/coreconcepts?id=bloc))
```
┌──────────── State ────────────┐
│ │
@ -209,15 +203,17 @@ interaction │ │ └──────▲────────
│ ▲
│ │
└────────── Event ────────────┘
```
2. The `bloc` process the events using the services provided by the `Domain` layer.
2. The `bloc` processes the events using the services provided by the `Domain` layer.
1. Convert DTO (Data Transfer Object) to domain model and Domain Model to DTO.
2. Domain model is the place where all your business logics, business validation and business behaviors will be implemented.
2. Domain model is the place where all your business logic, business validation and business behaviors will be implemented.
The Aggregate Roots, Entities and Value Objects will help to achieve the business logic.
3. Calling repositories to perform additional operations. The repositories interfaces are declared in `Domain`, implemented in `Infrastructure`.
You can reimplement the repository interface with different languages, such as `Rust`, `C++` or `Flutter`. etc.
3. Calling repositories to perform additional operations. The repositories interfaces are declared in the `Domain` layer and are implemented in the `Infrastructure` layer.
You can reimplement the repository interface with different languages, such as `Rust`, `C++` or `Dart`. etc.
```
Domain Infrastructure
@ -234,10 +230,9 @@ interaction │ │ └──────▲────────
│ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │
└────────────────────────────┴────────────────────────────────┘
```
4. Responsibility of [Unit of Work](https://martinfowler.com/eaaCatalog/unitOfWork.html) is to maintain a list of objects affected by a
business transaction and coordinates the writing out of changes and the resolution of concurrency problems((No intermediate state)).
4. The responsibility of [Unit of Work](https://martinfowler.com/eaaCatalog/unitOfWork.html) is to maintain a list of objects affected by a business transaction and coordinates the writing out of changes and the resolution of concurrency problems((No intermediate state)).
If any one persistence service fails, the whole transaction will be failed so, roll back operation will be called to put the object
back in initial state.
5. Handling operations (INSERT, UPDATE and DELETE) with SQLite to persis the data.
6. Saving or querying the data in the cloud to finish the operation.
6. Saving or querying the data in the cloud to finish the operation.

48
doc/TRANSLATION.md
View File

@ -2,28 +2,30 @@
You can help Appflowy in supporting various languages by contributing. Follow the steps below sequentially to contribute translations.
**NOTE: Translation files SHOULD be** `json` **files named in the format** `<lang_code>-<country_code>.json` **or just** `<lang_code>.json`**. eg:**`en.json`**,** `en-UK.json`
## Steps to add new language support
1. Add language key-value json file to `frontend/app_flowy/assets/translations/`. Refer `en.json` for format and keys.
2. Run `flutter pub run easy_localization:generate -S assets/translations/`.
3. Run `flutter pub run easy_localization:generate -f keys -o locale_keys.g.dart -S assets/translations`.
4. Add locale of the language (eg: `Locale('en', 'IN')`, `Locale('en')`) in `supportedLocales` list under `EasyLocalization` wrapper for flutter to support it.
This is located in `frontend/app_flowy/lib/startup/tasks/application_widget.dart` under `AppWidgetTask` class as shown below:
```dart
runApp(
EasyLocalization(
supportedLocales: const [ Locale('en') ], // <---- Add locale to this list
path: 'assets/translations',
fallbackLocale: const Locale('en'),
child: app),
);
```
## Steps to modify translations
## Steps to modify an existing translation
Translation files are located in : `frontend/app_flowy/assets/translations/`
1. Modify the specific translation file.
2. Run `flutter pub run easy_localization:generate -S assets/translations/`.
3. Run `flutter pub run easy_localization:generate -f keys -o locale_keys.g.dart -S assets/translations`.
2. Run `flutter pub run easy_localization:generate -S assets/translations/`
3. Run `flutter pub run easy_localization:generate -f keys -o locale_keys.g.dart -S assets/translations`
4. Verify that the translation has changed appropriately by compiling and running the app.
## Steps to add new language
**NOTE: Translation files SHOULD be** `json` **files named in the format** `<lang_code>-<country_code>.json` **or just** `<lang_code>.json`**. eg:**`en.json`**,** `en-UK.json`
1. Add language key-value json file to `frontend/app_flowy/assets/translations/`. Refer `en.json` for format and keys.
2. Run `flutter pub run easy_localization:generate -S assets/translations/`
3. Run `flutter pub run easy_localization:generate -f keys -o locale_keys.g.dart -S assets/translations`
4. Open the `frontend/app_flowy/lib/startup/tasks/application_widget.dart` file.
5. In the `AppWidgetTask` class, add the locale of the language you just created (eg: `Locale('en', 'IN')`, `Locale('en')`) to the `supportedLocales` List :
```dart
runApp(
EasyLocalization(
supportedLocales: const [Locale('en'), Locale('zh_CN')], // <---- Add locale to this list
path: 'assets/translations',
fallbackLocale: const Locale('en'),
child: app),
);
```

1
frontend/Makefile.toml
View File

@ -127,7 +127,6 @@ script_runner = "@shell"
BUILD_FLAG = "release"
TARGET_OS = "ios"
CRATE_TYPE = "staticlib"
BUILD_FLAG = "release"
FLUTTER_OUTPUT_DIR = "Release"
PRODUCT_EXT = "ipa"

8
frontend/app_flowy/linux/appflowy.desktop.temp Normal file
View File

@ -0,0 +1,8 @@
[Desktop Entry]
Name=AppFlowy
Comment=An Open Source Alternative to Notion
Icon=[CHANGE_THIS]/AppFlowy/flowy_logo.svg
Exec=[CHANGE_THIS]/AppFlowy/app_flowy
Categories=Office
Type=Application
Terminal=false

32
frontend/scripts/makefile/flutter.toml
View File

@ -14,7 +14,7 @@ run_task = { name = ["flutter-build", "copy-to-product"] }
[tasks.appflowy-linux]
dependencies = ["flowy-sdk-release"]
run_task = { name = ["flutter-build", "copy-to-product"] }
run_task = { name = ["flutter-build", "copy-to-product", "create-release-archive"] }
script_runner = "@shell"
[tasks.appflowy-dev]
@ -71,6 +71,9 @@ script = [
product=${PRODUCT_NAME}
cp -R ${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/app_flowy/build/${TARGET_OS}/${LINUX_ARCH}/${BUILD_FLAG}/bundle \
${output_path}/${product}
cp ${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/app_flowy/linux/appflowy.desktop.temp ${output_path}/${product}
cp ${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/app_flowy/assets/images/flowy_logo.svg ${output_path}/${product}
""",
]
script_runner = "@shell"
@ -92,6 +95,33 @@ script = [
]
script_runner = "@duckscript"
# The following tasks will create an archive that will be used on the GitHub Releases section
# The archives are created using different compression programs depending on the target OS
# The archive will be composed of all files that are located in the /Release/AppFlowy directory
[tasks.create-release-archive]
mac_alias = "create-release-archive-macos"
windows_alias = "create-release-archive-windows"
linux_alias = "create-release-archive-linux"
[tasks.create-release-archive-linux]
script = [
"cd ${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/app_flowy/product/${VERSION}/${TARGET_OS}/Release",
"tar -czf ${PRODUCT_NAME}-${TARGET_OS}-x86.tar.gz *"
]
[tasks.create-release-archive-windows]
script = [
# TODO
# "cd ${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/app_flowy/product/${VERSION}/${TARGET_OS}/Release/${PRODUCT_NAME}",
# "tar -czf ${PRODUCT_NAME}-${TARGET_OS}-x86.tar.gz *"
]
[tasks.create-release-archive-macos]
script = [
# TODO
# "cd ${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/app_flowy/product/${VERSION}/${TARGET_OS}/Release/${PRODUCT_NAME}",
# "tar -czf ${PRODUCT_NAME}-${TARGET_OS}-x86.tar.gz *"
]
[tasks.flutter-build]
script = [