-
Notifications
You must be signed in to change notification settings - Fork 43
Developer Guide
We are looking for contributors, so it is great to have you here! To get you started we try to summarize here some best practices and development information that might help you getting started with development on Piwigo-Android.
The simplest form of contribution is creation of and commenting on existing tickets. This helps to improve the app by knowing about bugs and the most wanted feature requests from the users and align our roadmap.
To do this, simply create an account on github and create a new ticket. We will then try to analyze them, assign some labels, come back with questions, link them to an upcoming release and finally solve them. If we decide to work on a ticket for the next release we try to assign it to a developer and if you are interested in contributing code for a ticket please remark it in the issue description or a comment.
In case you want a feature so much and the team did not yet find the time to work on it, you should consider a source code contribution. This android app is written in Java and is planned to stay with this in the next time, to allow even newbies in android development a quick ramp-up time until the first contribution is going live. We would like to see a ticket for each significant code change to have a place to discuss ideas before you invest and potentially waste a lot of time and to have a mechanism in place to ensure that we do not duplicate effort with several people working on the same bug or feature.
The contributions should be published as a PR (Pull Request) and reviewed by developers of the Piwigo-Mobile team. For this, please fork the project Piwigo/Piwigo-Android into your user space on github, commit the code changes there and create a pull request against the master branch in Piwigo/Piwigo-Android.
It is good practice to include unit tests for new features or bugfixes in the pull request. Another form of testing is performed by users on a pre-release-track via google play, before we publish a final release.
The app Piwigo-Android is licensed under the terms of the "GNU General Public License (GPL) in version 3, or (at your option) any later version of that license. By submitting code or artwork to the project by patches, pull request or any other form the authors guarantee that it is either their own work and they accept to distribute their content under this license or the contribution is (re-)distributable under the terms of this license. If not specifically marked with a dedicated copyright notice, the copyright of the source code is transfered to to Piwigo project as far as permitted by applicable law. If necessary for legal reasons the source code author(s) shall be extracted from the meta data of the version control system. Copyright notices in this project are mostly given with a reference to the year in form of xxxx-yyyy as a short cut with the meaning, that every year in the given range is a copyrightable year.
The app is developed using the Model-View-ViewModel architectural pattern, which essentially means, that we keep the business logic and the UI separated by the ViewModel sitting between them. In the view - normally the layout XML - we access the content via databinding from the view model. See activity_login.xml and LoginActivity.java. In the xml we declare a variable viewModel, which is set from the activity. Dynamic content and actions are linked to methods in the view model via @={} syntax. Not always simple to debug, but we hope that finally the development and maintenance is simplified.
Dagger 2 is used to inject dependencies. You might want to read some words about dependency injections to get some background. The main goal of using DI is to reach a good testability.
The roadmap of Piwigo-Android is planned using github milestones. We intend to have milestones for the upcoming 2-4 releases and one called Future Plans. From this you can see when we plan to do what. Active development normally happens only on the next upcoming release and the later releases are "just" planning what to do in which order. Milestone Future Plans will never be reached, it is a container for good ideas that we'd like to support once but we don't see it for the currently existing release milestones. Releases are created according the release checklist, normally in cycles of two: a beta release to add new features, perform user testing and finalize translation and a following stable release. During the development of new features for the next beta, the version code is odd and has a "-dev" suffix. During bugfix phase of the current beta for the next stable release the version code stays on the value of the development phase, but the version name suffix is changed to "-beta". The final version has an even version code and no version name suffix.
Localization is handled via the crowdin. There we have configured the android string resources and also the app store descriptions for translation. Creating new languages should therefore be possible purely in crowdin, followed by a merge of the PR created from crowdin.
The App it published in googles Play Store via Triple-T Gradle Play Publisher (GPP). For this we have a service API account and the key for it, as also the keystore for the APK signing, on the developers machines. We use App Bundles for here. Also the texts and images for the play store entry are in the code repository and synchronized to google via GPP. Publishing to f-droid is currently not yet set up, but it will also use the metadata from the GPP structure. For the releases f-droid will rely on version tags in git.
As you have read until here, you should know the most important principles, for remaining questions, please create either an issue, or use one of the communication channels in the README to get in touch with the Piwigo-Mobile team. We are your friends and will give our best to help you having fun in contributing to this nice project. In case it feels differently, remind us of what we promised here.