{"id":19466754,"url":"https://github.com/zulip/zulip-flutter","last_synced_at":"2025-04-07T11:08:07.977Z","repository":{"id":65559673,"uuid":"579929354","full_name":"zulip/zulip-flutter","owner":"zulip","description":"Future Zulip client using Flutter","archived":false,"fork":false,"pushed_at":"2024-05-22T22:42:41.000Z","size":7921,"stargazers_count":128,"open_issues_count":227,"forks_count":104,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-05-22T23:02:28.053Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zulip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-19T09:45:51.000Z","updated_at":"2024-05-28T21:57:35.759Z","dependencies_parsed_at":"2023-09-27T11:59:00.568Z","dependency_job_id":"d9e3e0f2-e418-469d-95f2-feff25cb3b44","html_url":"https://github.com/zulip/zulip-flutter","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zulip%2Fzulip-flutter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zulip%2Fzulip-flutter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zulip%2Fzulip-flutter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zulip%2Fzulip-flutter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zulip","download_url":"https://codeload.github.com/zulip/zulip-flutter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640464,"owners_count":20971557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T18:30:02.411Z","updated_at":"2025-04-07T11:08:07.956Z","avatar_url":"https://github.com/zulip.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zulip Flutter (beta)\n\nA Zulip client for Android and iOS, using Flutter.\n\nThis app is currently [in beta][beta].\nWhen it's ready, it [will become the new][] official mobile Zulip client.\nTo see what work is planned before that launch,\nsee the [milestones][] and the [project board][].\n\n[beta]: https://chat.zulip.org/#narrow/stream/2-general/topic/Flutter/near/1708728\n[will become the new]: https://chat.zulip.org/#narrow/stream/2-general/topic/Flutter/near/1582367\n[milestones]: https://github.com/zulip/zulip-flutter/milestones?direction=asc\u0026sort=title\n[project board]: https://github.com/orgs/zulip/projects/5/views/4\n\n\n## Using Zulip\n\nTo use Zulip on iOS or Android, install the [official mobile Zulip client][].\n\nYou can also [try out this beta app][beta].\n\n[official mobile Zulip client]: https://github.com/zulip/zulip-mobile#readme\n\n\n## Contributing\n\nContributions to this app are welcome.\n\nIf you're looking to participate in Google Summer of Code with Zulip,\nthis is one of the projects we intend to accept [GSoC 2025 applications][gsoc]\nfor.\n\n[gsoc]: https://zulip.readthedocs.io/en/latest/outreach/gsoc.html#mobile-app\n\n\n### Picking an issue to work on\n\nFirst, see the Zulip project guide to [your first codebase contribution][].\nFollow the instructions there for joining the Zulip community server,\nreading about [what makes a great Zulip contributor][],\nbrowsing through recent commits and the codebase,\nand the Zulip guide to Git.\n\nTo find possible issues to work on, see our [project board][].\nLook for issues up through the \"Launch\" milestone,\nand that aren't already assigned.\n\nFollow the Zulip guide to [picking an issue to work on][],\ntrying several issues until you find one you're confident\nyou'll be able to take on effectively.\n\n*After you've done that*, claim the issue by posting a comment\non the issue thread, saying you'd like to work on it\nand describing your progress.\n\n[your first codebase contribution]: https://zulip.readthedocs.io/en/latest/contributing/contributing.html#your-first-codebase-contribution\n[what makes a great Zulip contributor]: https://zulip.readthedocs.io/en/latest/contributing/contributing.html#what-makes-a-great-zulip-contributor\n[picking an issue to work on]: https://zulip.readthedocs.io/en/latest/contributing/contributing.html#picking-an-issue-to-work-on\n\n\n\u003cdiv id=\"getting-help\" /\u003e\n\n### Asking questions, getting help\n\nTo ask for help with working on this codebase, use the\n[`#mobile-dev-help`][mobile-dev-help] channel on chat.zulip.org.\nBefore participating there for the first time,\nbe sure to take a minute to read our\n[community norms][norms-getting-help].\n\nFor more in-depth advice on how to go beyond the minimum\nrepresented by our community norms, see\nZulip's [guide to asking great questions][]\nand the resources linked from there.\n\n[mobile-dev-help]: https://chat.zulip.org/#narrow/stream/516-mobile-dev-help\n[norms-getting-help]: https://zulip.com/development-community/#getting-help\n[guide to asking great questions]: https://zulip.readthedocs.io/en/latest/contributing/asking-great-questions.html\n\n\n### Submitting a pull request\n\nFollow the Zulip project's guide to your first codebase contribution\nfor [working on an issue][] and [submitting a pull request][].\nIt's important to take the time to make your work as\neasy as possible for others to review.\n\nTwo specific points to expand on:\n\n * Before we can review your PR in detail, your changes will need\n   tests.  See [\"Writing tests\"](#writing-tests) below.\n\n   It will also need all new and existing tests to be passing.\n   See [\"Tests\"](#tests) below about running the tests.\n\n * Your changes will need to be organized into\n   [clear and coherent commits][commit-style],\n   following [Zulip's commit style guide][commit-style].\n\n   This is always required before we can merge your PR.  Depending on\n   your changes' complexity, it may also be required before we can\n   review it in detail.  (The main exception is that if the change\n   should be a single commit, we can review it even with a messier\n   commit structure.)\n\n[working on an issue]: https://zulip.readthedocs.io/en/latest/contributing/contributing.html#working-on-an-issue\n[submitting a pull request]: https://zulip.readthedocs.io/en/latest/contributing/review-process.html\n[commit-style]: https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html\n\n\n## Getting started in developing this beta app\n\n### Setting up\n\nRunning the app requires only a standard Flutter setup,\nusing the Flutter `main` channel:\n\n1. Follow the [Flutter installation guide](https://docs.flutter.dev/get-started/install)\n   for your platform of choice.\n2. Switch to the latest version of Flutter by running `flutter channel main`\n   and `flutter upgrade` (see [Flutter version](#flutter-version) below).\n3. Ensure Flutter is correctly configured by running `flutter doctor`.\n4. Start the app with `flutter run`, or from your IDE.\n\nParts of our test suite require an additional dependency:\n\n5. Install SQLite, for example by running `sudo apt install libsqlite3-dev`.\n\nDeveloping on Windows requires\nan [additional step](docs/setup.md#autocrlf):\n\n6. Run `git config core.autocrlf input`.\n\nFor more details and help with unusual configurations,\nsee our [full setup guide](docs/setup.md).\n\nIf you're having trouble or seeing errors, take a look through our\n[troubleshooting section](docs/setup.md#troubleshooting).\nIf that doesn't resolve the issue, see the section above on\n[how to ask for help](#getting-help).\n\n\n### Flutter version\n\nWe use the latest Flutter from Flutter's main branch.\nUse `flutter channel main` and `flutter upgrade`.\n\nBecause each version of Flutter provides its own version of the\nDart SDK, this also means we use the latest Dart SDK.\n\nUsing the latest versions is the same thing Google does with\ntheir own Flutter apps.  It's valuable to us because it means\nwhen there's something we want to fix in Flutter,\nor a feature we want to add,\nwe can send a PR upstream and then use it as soon as it's merged.\n\nWe don't pin a specific Flutter version,\nbecause Flutter itself doesn't offer a way to do so.\nSo far that hasn't been a problem.  When it becomes one,\nwe'll figure it out; there are several tools for this in the Flutter\ncommunity.  See [issue #15][].\n\n[issue #15]: https://github.com/zulip/zulip-flutter/issues/15\n\n\n### Tests\n\nYou can run all our forms of tests with the `tools/check` script:\n\n```\n$ tools/check\n```\n\nSee `tools/check --help` for more information.\n\nThe two major test suites are the Dart analyzer, which performs\ntype-checking and linting; and our unit tests, located in the `test/`\ndirectory.\n\nYou can run these suites directly with the commands `flutter analyze`\nand `flutter test` respectively.  Both commands accept a list of file\nor directory paths to operate on, and other options.  Particularly\nrecommended is a command like\n```\n$ flutter test test/foo/bar_test.dart --name 'baz'\n```\nwhich will run only the tests in `test/foo/bar_test.dart`,\nand within those only the tests with names matching `baz`.\n\nWhen editing in an IDE, the IDE should give you the exact same feedback\nas `flutter analyze` would.  When editing a test file, the IDE can also\nrun individual tests for you.\nSee [upstream docs on `flutter test`][flutter-cookbook-unit-tests].\n\n[flutter-cookbook-unit-tests]: https://docs.flutter.dev/cookbook/testing/unit/introduction\n\n\n## Notes\n\n### UI design\n\nFor issues that call for building new UI, we typically have a\ndesign in Figma which will be linked from the issue description.\n\nWhen there is a design in Figma, a PR implementing the issue\nshould match the design exactly, except where there's a\ngood reason to make things different.\nLike with any difference between a PR and previous plans,\nyou should [explain the difference](https://zulip.readthedocs.io/en/latest/contributing/reviewable-prs.html#explain-your-changes)\nclearly in your PR description.\n\nFor colors, padding, font sizes, and similar design details,\nit's rare to have a good reason to differ from the\ndesign in Figma.\nWhen [reviewing your work](https://zulip.readthedocs.io/en/latest/contributing/reviewable-prs.html#review-your-own-work)\n(which you should do before every PR),\ntake some time to look closely through all the details of\nthe design in Figma\nand confirm that they're matched in your PR.\n\nIn our code, many colors and other details appear on `DesignVariables`\nor similar classes like `ContentTheme`.  If you need a Figma variable\nwhich doesn't yet appear in our code, please add it.\n\n\n### Writing tests\n\nWe write tests for all changes to the Dart code in the app.\nBecause Flutter and Dart have excellent facilities for testing,\nwe're able to efficiently write tests even for kinds of code\nthat often go untested: UI code, and code that makes network\nrequests or calls external APIs.\n\nYou may sometimes find code that doesn't have tests.\nThis is generally code from the early prototype phase;\nwhen we make changes to it, we write tests for the changes,\nand often take the opportunity to write tests for the\nexisting logic too.\n\nWhen it's time to write a test, look around at existing tests in the\nsame test file or at our existing tests for similar code, and follow\nthe patterns we use there.  Notes on specific kinds of tests:\n\n * For UI code, we use Flutter's standard `testWidgets` function.\n   Many widgets will interact with the user's data; see docs on\n   our `TestZulipBinding` and `TestGlobalStore`, and existing\n   tests that use `testBinding.globalStore`, for how to manipulate\n   test data there.\n\n * For code that makes Zulip API requests, use `FakeApiConnection`;\n   see its docs and the existing tests that use it.\n\n * For code that makes other network requests, look for similar\n   existing tests; or see our `FakeHttpClient`, and use\n   `withHttpClient` from `package:http` to cause the code under test\n   to use it.\n\n * For code that invokes Flutter plugins or otherwise calls external\n   APIs, see our `ZulipBinding` class.  If there isn't an existing\n   member of that class that wraps the API you're using, then you'll\n   need to add one; follow the existing examples.\n\n\n#### `check` vs. `expect`\n\nFor our tests, we use [the `checks` package][package-checks].\nThis is a new package from the Dart team, currently in preview,\nwhich is [intended to replace][package-checks-migration] the\nold `matcher` package.\n\nThis means that if you see example test code elsewhere that\nuses the `expect` function, we'd prefer to translate it into\nsomething in terms of `check`.  For help with that,\nsee the [`package:checks` migration guide][package-checks-migration]\nand the package's [API docs][package-checks-api].\n\nBecause `package:checks` is still in preview, the Dart team is\nopen to feedback on the API to a degree that they won't be\nafter it reaches 1.0.  So where we find rough edges, now is a\ngood time to [report them as issues][dart-test-tracker].\n\n[package-checks]: https://pub.dev/packages/checks\n[package-checks-api]: https://pub.dev/documentation/checks/latest/checks/checks-library.html\n[package-checks-migration]: https://github.com/dart-lang/test/blob/master/pkgs/checks/doc/migrating_from_matcher.md\n[dart-test-tracker]: https://github.com/dart-lang/test/issues\n\n\n### Editing API types\n\n#### Server compatibility\n\nWe support Zulip Server 4.0 and later.\n\nFor API features added in newer versions, use `TODO(server-N)`\ncomments (like those you see in the existing code.)\n\n\n#### Require all parameters in API constructors\n\nIn our API types, constructors should generally avoid default values for\ntheir parameters, even `null`.  This means writing e.g. `required this.foo`\nrather than just `this.foo`, even when `foo` is nullable.\n\nWe do this because it's common in the Zulip API for a null or missing value\nto be quite salient in meaning, and not a boring value appropriate for a\ndefault, so that it's best to ensure callers make an explicit choice.\n\nIf passing explicit values in tests is cumbersome, a factory function\nin `test/example_data.dart` is an appropriate way to share defaults.\n\n\n#### Generated files\n\nWhen editing any of the type definitions in our API, you'll need to\nkeep up to date the corresponding generated code\n(which handles converting JSON to and from our types).\n\nTo do this, run the following command:\n```\n$ dart run build_runner watch --delete-conflicting-outputs\n```\n\nThat `build_runner watch` command watches for changes\nin relevant files and updates the generated code as needed.\n\nWhen the `build_runner watch` command has finished its work and\nis waiting for more changes, you may find it convenient to\nsuspend it by pressing Ctrl+Z before you edit the code further.\nWhile suspended, the command will not run.\nAfter editing the source files further, you can update the\ngenerated files again by running the command `fg` in the\nterminal where `build_runner watch` had been running.\nThe `fg` command causes the suspended command to resume running\n(in the foreground, hence the name `fg`), just like it was doing\nbefore Ctrl+Z.\n\nIf a PR is missing required updates to these generated files,\nCI will fail at the `build_runner` suite.\n\n\n### Upgrading Flutter\n\nWe regularly increment our lower bounds on Flutter and Dart versions,\nto make sure there's not too much divergence in the versions people\nare using.\n\nWhen there's a new beta (which happens a couple of times per month),\nthat's a good prompt to do this.  We also do this when there's a\nnew PR merged that we particularly want to take.\n\nTo update the version bounds:\n* Use `flutter upgrade` to upgrade your local Flutter and Dart.\n* Run `tools/upgrade flutter-local`, which makes a commit updating\n  `pubspec.yaml` and `pubspec.lock` to match your local Flutter.\n* Build and run the app for a quick smoke-check.\n* Send the changes as a PR.\n\n\n### Upgrading dependencies\n\nWhen adding or upgrading dependencies, try to keep our generated files\nupdated atomically with them.\n\nIn particular the CocoaPods lockfiles\n`ios/Podfile.lock` and `macos/Podfile.lock`\nfrequently need an update when dependencies change.\nThis can only be done in a macOS development environment.\n\nIf you have access to a Mac,\nthen for upgrading dependencies, use the script `tools/upgrade`.\nOr after adding a new dependency, run the commands\n`(cd ios \u0026\u0026 pod update) \u0026\u0026 (cd macos \u0026\u0026 pod update)`\nto apply any needed updates to the CocoaPods lockfiles.\n\nIf you don't have convenient access to a Mac, then just mention\nclearly in your PR that the upgrade needs syncing for CocoaPods,\nand someone else can do it before merging the PR.\n\n(Ideally we would validate these automatically in CI: [#329][].\nSeveral other kinds of generated files are already validated in CI.)\n\n[#329]: https://github.com/zulip/zulip-flutter/issues/329\n\n\n### Code formatting\n\nLike the [upstream Flutter project itself][flutter-no-dartfmt],\nwe [don't use `dart format`][zulip-no-dartfmt]\nor other auto-formatters.\nInstead, follow the style you see in the existing code.\n\nIt's OK if in your first few PRs you haven't yet picked up all the\nnuances of our style.  Reviewers will point out nits as they see them.\n\nIf your editor or IDE automatically reformats the existing code,\nyou'll want to turn that off.  Please also mention it in Zulip\non chat.zulip.org and describe what editor you were using;\nwe'd like to include such configuration directly in the repo\nso it's automatic for the next person.  We already have that\n[for VS Code][vscode-disable-reformat], and it seems to be the\ndefault for Android Studio / IntelliJ, but when there are cases\nwe haven't covered we'd like to know about them.\n\n[flutter-no-dartfmt]: https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#formatting\n[zulip-no-dartfmt]: https://github.com/zulip/zulip-flutter/issues/229#issuecomment-1642807019\n[vscode-disable-reformat]: https://github.com/zulip/zulip-flutter/pull/230\n\n\n### Translations and i18n\n\nWhen adding new strings in the UI, we set them up to be translated.\nFor details on how to do this, see the [translation doc](docs/translation.md).\n\n\n### Desktop support\n\nThis app is intended for use on mobile platforms, specifically\nAndroid and iOS.\n\nOn desktop platforms, we support running the app for development\nbut not for general use.  In particular this means:\n\n * The layout and UI are designed for mobile.  We don't spend time\n   on adapting the app to desktop UI features or paradigms.\n\n * External platform integrations (like opening a link,\n   taking a photo, etc.) are built only for Android and iOS.\n   We don't spend time making them work on other platforms.\n\n * On the other hand the app runs, and core functionality works,\n   on at least Linux and macOS.  Currently no regular contributor\n   uses it on Windows, but we accept fixes to keep it running there too.\n\nThe reason we support desktop platforms at all is that\nfor development it's sometimes useful to run the app on desktop.\nFor example, this makes it easy to resize the window arbitrarily,\nwhich can be helpful for testing layout behavior.\n\n\n## License\n\nCopyright (c) 2022 Kandra Labs, Inc., and contributors.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\nThe software includes some works released by third parties under other\nfree and open source licenses. Those works are redistributed under the\nlicense terms under which the works were received.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzulip%2Fzulip-flutter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzulip%2Fzulip-flutter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzulip%2Fzulip-flutter/lists"}