Skip to content

Latest commit

 

History

History
149 lines (114 loc) · 7.35 KB

CONTRIBUTING.md

File metadata and controls

149 lines (114 loc) · 7.35 KB

Contributing

We welcome contributions of all kinds and sizes. This includes everything from simple bug reports to large features.

Table of Contents

Workflow

  • We love GitHub issues!
  • For small feature requests, an issue first proposing it for discussion or demo implementation in a PR suffice
  • For big feature requests, please open an issue to avoid wasting time on a feature that might need reworking
  • Small pull requests for things like typos, bug fixes, etc are always welcome

Getting started

  1. Ensure that you have the latest Android SDK tools installed on your machine
  2. Fork the repository to create a copy in your GitHub account. The forked repository should be accessible at https://github.com/<your-username>/noice
  3. Clone the forked repository to your machine
  4. Open the existing project using Android Studio or any editor of your choice

Translations

Noice is currently being maintained by a single developer. To avoid context switches, I have decided to accept translation contributions through GitHub only and will not be using a dedicated service for Translations, such as Weblate.org, in the foreseeable future.

Adding translations to Noice is rather easy on GitHub as well

  1. Fork the repo

  2. To create and edit a strings.xml file, you should ideally be using Android Studio. If you don't have Android Studio set up on your local machine, that's fine too.

    • To create a new strings.xml file using Android Studio

      1. Open the new file wizard under File > New > Android resource file
      2. From the Available qualifiers, add Locale to the Chosen qualifiers
      3. Select the correct language and region, and create the new strings.xml file

    • Use this list to find the correct path for a new strings.xml file otherwise

  3. Translate all the strings in values/strings.xml

  4. If you're updating translations for an existing language, see this issue where we keep track of missing and potentially outdated translations.

  5. Translate the F-Droid and Play Store metadata. See docs and an example

    • Do not add screenshots. Screenshots are generated using Fastlane before creating a release
    • Do not add icon as it is untranslated
    • You are free to create a featureGraphic. Its dimensions should be 1024wx500h and it should be opaque

  6. Add your name to the translation credits section in the AboutFragment

    • Add the required strings to the values/dont_translate.xml. See example

    • Add the required item to the TRANSLATIONS array in AboutFragment. See example

    • The naming convention for credit strings is as follows where the index is an integer denoting the number of revisions for a particular locale. For new locales, the index is 0. For existing locales, the index is its last value for that locale incremented by one.

      1. credits__translation_<language code>_<region, if any>_<index>: for descriptions
      2. credits__translation_<language code>_<region, if any>_<index>__url: for author's URL

  7. Create a Pull Request proposing the new changes. On creating the pull request, Noice will run a set of GitHub actions that will check syntactical errors in the proposed changes.

Adding sounds

Feel free to add more sounds to Noice taking the following under consideration.

  • Looping sounds should be at least 30 seconds and at most 2 minutes long. These are not hard limits but the goal should be to minimize the ease of recognizing recurring patterns in loops
  • All sounds should be encoded to mp3 format with the following configuration. I use Audacity for editing audio
    • Sample rate: 44.1 kHz
    • Quality: Standard, 170-210 kbps
    • Variable Speed: Fast
    • Channel Mode: Stereo

Best Practices

  • Let Android Studio do the code formatting
  • Include tests when adding new features
  • When fixing bugs, start with adding a test that highlights how the current behavior is broken. This is not mandatory since it is not always possible/approachable

Guiding Principles

  • We allow anyone to participate in our projects. Tasks can be carried out by anyone that demonstrates the capability to complete them
  • Always be respectful of one another. Assume the best in others and act with empathy at all times
  • Collaborate closely with individuals maintaining the project or experienced users. Getting ideas out in the open and seeing a proposal before it's a pull request helps reduce redundancy and ensures we're all connected to the decision-making process

Releases

Noice is regularly updated on Google Play Store and F-Droid. A commit with the following changes is necessary to prepare a new release.

  1. It must bump app version name and code in app/build.gradle
  2. It should add the release notes in en-US locale in the Fastlane metadata. Release notes are added to a new file at path fastlane/metadata/android/en-US/changelogs/<version-code>.txt
  3. It should update the app's descriptive assets (Fastlane metadata) if required
  4. It should update generated screenshots if required (fastlane generate_screenshots)

Play Store

Noice uses GitHub actions to automatically build and push releases to Google Play store.

  • We have been strictly following Semantic Versioning since 0.4.x
  • New translations are considered as a feature
  • All releases tagged in Git repository are pushed to beta track on the Play Store. After ample time, a release is manually promoted to the production track for general availability.
  • In case a feature is merged into the master branch and a patch release needs to be created for the latest public release, create a temporary branch with pattern Major.Minor.x e.g., 1.1.x. Tag any further patch releases to a commit in this branch. Before the next non-patch release, the temporary branch can be merged into master.

F-Droid

F-Droid releases are picked by its builder based on the latest tag. See the metadata file for more information.