mirror/iNaturalistReactNative
1
0
Fork 0
mirror of https://github.com/inaturalist/iNaturalistReactNative.git synced 2025-12-23 14:08:56 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs: add commit style and translation source guidance (#2296)

Browse Source 
* docs: add commit style and translation source guidance
* docs: specify that ppl should work on unassigned issues; separate and update getting started from submitting
This commit is contained in:
Ken-ichi
2024-10-25 10:00:10 -07:00
committed by GitHub
parent 005230404c
commit 69a5956bc6
2 changed files with 133 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
CONTRIBUTING.md
View File

@@ -1,36 +1,59 @@
# Contribution Guidelines for iNaturalistReactNative
Welcome! We're excited that you're interested in contributing to the iNaturalist React Native mobile application. Below you'll find some guidelines that will help you contribute to our project.
Welcome! We're excited that you're interested in contributing to the iNaturalist React Native mobile application. Below you'll find some guidelines that will help you contribute to our project, whether you're on staff or a volunteer.
We welcome volunteer contributions! This app is still early in its development and a lot of things are in flux, but there's usually something to work on. Please keep the following in mind:
Please keep the following in mind:
1. Work on [existing issues](https://github.com/inaturalist/iNaturalistReactNative/issues) (though if you have ideas for improvement that aren't directly related to features, let us know)
1. Leave a comment on the issue so we can assign you and other people know not to work on it
1. Work on [existing, unassigned issues](https://github.com/inaturalist/iNaturalistReactNative/issues?q=is%3Aissue+is%3Aopen+no%3Aassignee) (feature requests should go through the [Forum](https://forum.inaturalist.org/c/feature-requests/16))
1. Leave a comment on the issue you want to work on so we can assign you and other people know not to work on it
1. Name your branch starting with the issue number and then something descriptive, e.g. `123-login-with-locale-crash`
1. We try to review pull requests as soon as we can, but that might be up to a week or two
## Getting Started
1. Fork the repository.
2. Clone the forked repository to your local machine.
3. Follow [the README](README.md) to setup your local repository.
4. Create a new branch for the issue you're working on; the branch name should start with the issue number and by concise but descriptive, e.g. `123-login-with-locale-crash`.
5. Make changes to the codebase.
6. Push your changes to your forked repository.
1. Fork the repository
1. Clone the forked repository to your local machine
1. Follow [the README](README.md) to set up your dev environment
1. Create a new branch for the issue you're working on; the branch name should start with the issue number and be concise but descriptive, e.g. `123-login-with-locale-crash`
1. Start coding!
## Code Style
- We use [ESLint](https://eslint.org/) to enforce our code style; you should have this integrated into your editor / IDE
- We also have enabled a pre-commit hook to run `eslint --fix --quiet` on all staged files. This will fix issues that can be fixed automatically and should prevent commits that violate the rules
- We only have partial TypeScript adoption. It would be nice if new files were in TypeScript and those files were type safe, but it's not a requirement
## Commit Style
Please follow this guidance when committing to the main branch, including merge commits from PRs. Atomic commits in branches that don't make it into main can be more freeform.
1. Try to use the [imperative mood](https://www.git-basics.com/docs/git-commit/commit-message-rules), so your message should fill in the blank in, "If applied, this commit will \_\_\_\_\_"
1. Describe the impact on the end user if possible, so "Fix broken photo sharing in iOS 18" would be better than "Switch to a fork of photo-sharing-library-x"
1. Append developer-relevant details on subsequent lines, e.g.
```
Fix broken photo sharing in iOS 18
* Switch to fork of photo-sharing-library-x
* Minor UI touch-ups
```
1. Include `Closes #1234` on a subsequent line if your commit closes issue 1234; that will automatically close the issue on GitHub and helps link commits to the issues they address. Example
```
Fix broken photo sharing in iOS 18
Closes #1234
```
1. Semantic commit labels are fine (e.g. `fix: broken photo sharing in iOS 18`), but we don't (yet) require them
## Submitting Changes
1. Make sure your changes are up-to-date with the latest changes in the main repository.
2. Make sure your code is well-tested and passes all unit and integration tests.
3. It would be nice if you could run e2e tests locally with your own app credentials.
4. Create a pull request to the main repository with your changes.
1. Ensure tests are passing (run `npm test`). If tests are not passing we will not merge your PR
1. Ensure your branch is up-to-date with the main branch of the primary repository
1. Ensure your branch has no merge conflicts with the `main` branch. We will not merge PRs with conflicts
1. Create a pull request to the primary repository with your changes
## Guidelines
- Give your pull request a **clear and descriptive title** (e.g. "Remove predictions state on blur and focus in ARCamera") and a comment that includes a reference to the issue number (e.g. "Closes #123" or "Partially addresses #123" in case of an open issue) and maybe a detailed description of the changes you've made.
- If you're adding new features or functionality differing from the description in the issue, please provide a clear explanation of how this work differs from what the issue describes.
- Feel free to ask any questions or raise any concerns you have.
- Please make sure your code includes unit tests, and our linting rules were applied (should happen automatically).
## Pull Request Guidelines
- Give your pull request a **clear and descriptive title** (e.g. "Remove predictions state on blur and focus in ARCamera") and a comment that includes a reference to the issue number (e.g. "Closes #123" or "Partially addresses #123" in case of an open issue) and maybe a detailed description of the changes you've made
- Please do not refer to the issue number in the PR title. Do that in the comment / body.
- If you're adding new features or functionality differing from the description in the issue, please provide a clear explanation of how this work differs from what the issue describes
- Feel free to ask any questions or raise any concerns you have
## Code Style Guide
- We use [ESLint](https://eslint.org/) to enforce our code style guide.
- We have enabled several eslint plugins to enforce best practices, e.g. in testing and accessibility. We also have enabled a pre-commit hook to run `eslint --fix --quiet` on all staged files. This will fix issues that can be fixed automatically.
## Issues and Bugs
If you find an issue or bug in our application, please report it by opening a new issue in the repository. Please include a clear and detailed description of the issue, steps to reproduce the issue, and any relevant screenshots or error messages.

93
README.md
View File

@@ -92,17 +92,100 @@ Run `npm run e2e:build:android && npm run e2e:test:android` to build the APK for
## Translations
### Adding new text
### Adding and changing new source strings
Source strings are in `src/i18n/strings.ftl` and should be in US English. Don't edit the files in `src/i18n/l10n/` because they will get overwritten when we pull in translations. All translation is done by volunteers on [Crowdin](https://crowdin.com/editor/inaturalistios/724), so please follow these guidelines to make things easier for those generous people.
1. **Labels should match content as closesly as possible** (without exceeding 100 characters)
* Bad
```fluent
collection-project-screen-title = ABOUT COLLECTION PROJECTS
```
* Good
```fluent
ABOUT-COLLECTION-PROJECTS = ABOUT COLLECTION PROJECTS
```
1. **Labels should change when the content changes**
* Bad
* Old
```fluent
ABOUT-COLLECTION-PROJECTS = ABOUT COLLECTION PROJECTS
```
* New
```fluent
ABOUT-COLLECTION-PROJECTS = ABOUT COLLECTION AND UMBRELLA PROJECTS
```
* Good
* Old
```fluent
ABOUT-COLLECTION-PROJECTS = ABOUT COLLECTION PROJECTS
```
* New
```fluent
ABOUT-COLLECTION-AND-UMBRELLA-PROJECTS = ABOUT COLLECTION AND UMBRELLA PROJECTS
```
1. **Annotate strings with comments** unless the string is very self-descriptive
* Bad
```fluent
Change-date = Change date
```
Is this a verb phrase or a noun phrase? Are we talking about spare change in your pocket?
* Good
```fluent
# Label for a button that changes a selected date
Change-date = Change date
```
1. **Use double-dashes to append extra context to keys and to keep them unique and descriptive.** For example, translators might need to translate the word "Unknown" differently if it refers to a place or a taxon, so you might include both `Unknown--place = Unknown` and `Unknown--taxon = Unknown`
1. **Accessibility hints** are used by screen readers to describe what happens
when the user interacts with an element. The [iOS Guidelines](https://developer.apple.com/documentation/uikit/uiaccessibilityelement/1619585-accessibilityhint) define it as "A string that briefly describes the result of performing an action on the accessibility element." We write them in third person singular ending with a period
1. **Pluralize text with a count** using [selectors](https://projectfluent.org/fluent/guide/selectors.html)
* Bad
```fluent
x-observations = { $count } observations
```
* Good
```fluent
x-observations = { $count } { $count ->
[one] observation
*[other] observations
}
```
1. **Avoid variables when possible.** Variables make translation and static code checks harder
* Bad
```fluent
quality-grade-with-label = Quality Grade: { $qualityGrade }
```
* Good
```fluent
quality-grade-with-label--research = Quality Grade: Research
quality-grade-with-label--needs-id = Quality Grade: Needs ID
quality-grade-with-label--casual = Quality Grade: Casual
```
There are only 3 possible quality grades, so this can just be three separate strings. Translators don't have to worry about the possible values of `$qualityGrade` and it's much easier to check for unglobalized or unused keys.
### Adding new text to code
1. Add new strings in English to `src/i18n/strings.ftl` using [Fluent syntax](https://projectfluent.org/fluent/guide/), e.g.
```Fluent
```fluent
# Header for a paragraph describing projects
ABOUT-PROJECTS = ABOUT
# Text describing what projects are
projects-description =
Projects are really great, probably iNat's best feature.
```
Try to match case and strike a balance between specificity and reusability when choosing a key. Please add context comments to help translators understand how the text is used, avoid variables whenever possible, and try to keep `strings.ftl` alphabetized by key.
1. Run `npm run translate` to validate strings and build the JSON files i18next needs to access text in the app
1. In a commponent, use the `useTranslation` hook to reference your new string, e.g.
```jsx
@@ -120,7 +203,7 @@ Run `npm run e2e:build:android && npm run e2e:test:android` to build the APK for
When components need to be included around interpolated variables, use the `<Trans />` component:
Fluent:
```Fluent
```fluent
Welcome-user = <0>Welcome back,</0><1>{ $userHandle }</1>
```
@@ -137,7 +220,7 @@ Run `npm run e2e:build:android && npm run e2e:test:android` to build the APK for
/>
```
### Translating text
### Pushing / Pulling Translations
We manage translations through Crowdin. Actually updating the translation files should be largely automated, but this is what it looks like to do it manually (you must have the [Crowdin CLI](https://github.com/crowdin/crowdin-cli) installed and have an [access token](https://crowdin.com/settings#api-key) associated with a Crowdin user that can post files to the specified project):