mirror of
https://github.com/deltachat/deltachat-android.git
synced 2025-10-03 09:49:21 +02:00
add CONTRIBUTING.md (#2893)
* add a basic CONTRIBUTONG.md * link CONTRIBUTING.md from README.md * add links, slight rewordings * Update CONTRIBUTING.md Co-authored-by: link2xt <link2xt@testrun.org> * use links redirecting to the user's locale * Update CONTRIBUTING.md --------- Co-authored-by: link2xt <link2xt@testrun.org>
This commit is contained in:
bjoern
GitHub
parent
aa75d9da84
commit
141294ae12
2 changed files with 155 additions and 0 deletions
153
CONTRIBUTING.md
Normal file
153
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
# Contributing Guidelines
|
||||
|
||||
Thank you for looking for ways to help on Delta Chat Android!
|
||||
|
||||
This document tries to outline some conventions that may not be obvious
|
||||
and aims to give a good starting point to new contributors.
|
||||
|
||||
|
||||
## Reporting Bugs
|
||||
|
||||
If you found a bug, [report it on Github](https://github.com/deltachat/deltachat-android/issues).
|
||||
|
||||
Project maintainers may transfer bugs that are not UI specific
|
||||
(eg. network, database or encryption related)
|
||||
to [Delta Chat Core](https://github.com/deltachat/deltachat-core-rust/issues).
|
||||
If you assume beforehand, that the bug you've found belongs to Core,
|
||||
you can report there directly.
|
||||
|
||||
Please search both open and closed issues to make sure your bug report is not a duplicate.
|
||||
|
||||
For community interactions around Delta Chat
|
||||
please read our [Community Standards](https://delta.chat/community-standards).
|
||||
|
||||
|
||||
## Proposing Features
|
||||
|
||||
If you have a feature request,
|
||||
create a new topic on the [Forum](https://support.delta.chat/c/features/6).
|
||||
|
||||
|
||||
## Rough UX Philosophy
|
||||
|
||||
Some rough ideas, that may be helpful when thinking about how to enhance things:
|
||||
|
||||
- Work hard to avoid options and up-front choices.
|
||||
Thinking about concrete user stories may help on that
|
||||
- Avoid to speak about keys and other hard to understand things in the primary UI
|
||||
- The app shall work offline as well as with bad network
|
||||
- Users do not read (much)
|
||||
- Consistency matters
|
||||
- Offer only things that are highly useful to many people in primary UI.
|
||||
If really needed, bury other things eg. in some menus
|
||||
- The app should be for the many, not for the few
|
||||
|
||||
|
||||
## Contributing Code
|
||||
|
||||
The [README](./README.md) explains in detail how to set up the build environment.
|
||||
Please follow all steps precisely.
|
||||
If you run into troubles,
|
||||
ask on of the [cummunication channels](https://delta.chat/contribute) for help.
|
||||
|
||||
To contribute code,
|
||||
[open a Pull Request](https://github.com/deltachat/deltachat-android/pulls).
|
||||
|
||||
If you have write access to the repository,
|
||||
push a branch named `<username>/<feature>`
|
||||
so it is clear who is responsible for the branch,
|
||||
and open a PR proposing to merge the change.
|
||||
Otherwise fork the repository and create a branch in your fork.
|
||||
|
||||
Please add a meaningful description to your PR
|
||||
so that reviewers get an idea about what the modifications are supposed to do.
|
||||
|
||||
A meaningful PR title is helpful for [updating `CHANGELOG.md` on releases](./RELEASE.md)
|
||||
(CHANGELOG.md is updated manually
|
||||
to only add things that are at least roughly understandable by the end user)
|
||||
|
||||
If the changes affect the user interface,
|
||||
screenshots are very helpful,
|
||||
esp. before/after screenshots.
|
||||
|
||||
|
||||
### Coding Conventions
|
||||
|
||||
Source files are partly derived from different other open source projects
|
||||
and may follow different coding styles and conventions.
|
||||
|
||||
If you do a PR fixing a bug or adding a feature,
|
||||
please embrace the coding convention you see in the corresponding files,
|
||||
so that the result fits well together.
|
||||
|
||||
Do not refactor or rename things in the same PR
|
||||
to make the diff small and the PR easy to review.
|
||||
|
||||
Project language is Java.
|
||||
|
||||
By using [Delta Chat Core](https://github.com/deltachat/deltachat-core-rust)
|
||||
there is already a strong separation between "UI" and "Model".
|
||||
Further separations and abstraction layers are often not helpful
|
||||
and only add more complexity.
|
||||
|
||||
Try to avoid premature optimisation
|
||||
and complexity because it "may be needed in some future".
|
||||
Usually, it is not.
|
||||
|
||||
Readable code is better than having some Java paradigms fulfilled.
|
||||
Classic Java has a strong drive to add lots of classes, factories, one-liner-functions.
|
||||
Try to not follow these patterns and keep things really on point and simple.
|
||||
If this gets in conflict with embracing existing style, however,
|
||||
consistency with existing code is more important.
|
||||
|
||||
The "Delta Chat Core" is a high-level interface to what the UI actually needs,
|
||||
data should be served in a form that the UI do not need much additional work.
|
||||
If this is not the case, consider a feature proposal to "Delta Chat Core".
|
||||
|
||||
|
||||
### Merging Conventions
|
||||
|
||||
PR are merged usually to the branch `main` from which [releases](./RELEASE.md) are done.
|
||||
|
||||
As a default, do a `git rebase main` in case feature branches and `main` differ too much.
|
||||
|
||||
Once a PR has an approval, unless stated otherwise, it can be merged by the author.
|
||||
A PR may be approved but postponed to be merged eg. because of an ongoing release.
|
||||
|
||||
To ensure the correct merge merge strategy, merging left up to the PR author:
|
||||
|
||||
- Usually, PR are squash-merged
|
||||
as UI development often results in tiny tweak commits that are not that meaningful on their own.
|
||||
- If all commits are meaningful and have a well-written description,
|
||||
they can be rebased-merged.
|
||||
|
||||
If you do not have write access to the repository,
|
||||
you may leave a note in the PR about the desired merge strategy.
|
||||
|
||||
|
||||
## Translations
|
||||
|
||||
Translations are done via [Transifex](https://explore.transifex.com/delta-chat/),
|
||||
you can log in there with your E-Mail Address or with a Github or Google handle.
|
||||
You find two projects there:
|
||||
- "Delta Chat App" contains the strings used in the app's UI
|
||||
- "Delta Chat Website" contains the offline help from "Settings / Help"
|
||||
as well as the pages used on <https://delta.chat>
|
||||
|
||||
Most strings and the whole help are used for all systems
|
||||
(Android, iOS, Linux, Windows, macOS)
|
||||
and should be formulated accordingly.
|
||||
|
||||
If you want to change the english sources,
|
||||
do a PR to [`strings.xml`](https://github.com/deltachat/deltachat-android/blob/main/res/values/strings.xml)
|
||||
or to [`help.md`](https://github.com/deltachat/deltachat-pages/blob/master/en/help.md).
|
||||
Again, please do not mix adding things and refactorings, esp. for `help.md`,
|
||||
this would require retranslations and should be considered carefully.
|
||||
|
||||
|
||||
## Other Ways To Contribute
|
||||
|
||||
For other ways to contribute, refer to the [website](https://delta.chat/contribute).
|
||||
|
||||
If you think, something important is missed in this overview,
|
||||
please do a PR to this document :)
|
||||
|
|
@ -8,6 +8,8 @@ The APK can also be downloaded from [get.delta.chat](https://get.delta.chat).
|
|||
For the core library and other common info, please refer to the
|
||||
[Delta Chat Core Library](https://github.com/deltachat/deltachat-core-rust).
|
||||
|
||||
For general contribution hints, please refer to [CONTRIBUTING.md](./CONTRIBUTING.md).
|
||||
|
||||
<img alt="Screenshot Chat List" src="docs/images/2019-01-chatlist.png" width="298" /> <img alt="Screenshot Chat View" src="docs/images/2019-01-chat.png" width="298" />
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue