Skip to content

Latest commit

 

History

History
148 lines (91 loc) · 8.23 KB

CONTRIBUTING.md

File metadata and controls

148 lines (91 loc) · 8.23 KB
Raw

Contributing Guidelines

General Feedback

Create a new issue on our Issues page. You can write your feedback either in English (recommended) or in Japanese.

Issue reports

Search for existing issues first. If you find your issue previously reported, post your case to that issue; otherwise, create a new one by filling up the “Bug report” template. Do not hesitate to post the same phenomenon as the existing issue as long as there are fewer than 10 cases. Multiple instances help a lot in finding the cause. In that situation, include your environment (versions of both CotEditor and macOS) in your post.

If possible, attach screenshots or screencasts of the issue you face. It is also helpful to attach sample files that can reproduce the issue.

If your issue relates to the syntax highlight, include the sample code that can reproduce the unwanted highlight in your post.

Feature requests

Search for existing requests first. If you find your idea among the requests already posted, post your comment on that issue; otherwise, create a new one by filling out the “Feature request” template. Create an issue per feature instead of listing multiple features in a single post.

Pull Requests

General Code Improvements

Bug fixes and improvements are welcome. If you want to add a new feature or make a major change, it's better to ask the team first whether your idea will be accepted.

By adding code, please follow our coding style guide below.

Localizations

Fixing/updating existing localizations is always welcome. See each .xcstrings file to find which strings need to be localized or reviewed by native speakers. By localization, please refer to the comments and key naming so that you can know where and how each string will be used. If you are uncertain, feel free to ask @1024jp.

If your localization destroys some layout in views, try first making the sentence shorter. However, if it's impossible, then just tell us about it with a screenshot when you make a pull request. We'll update the view to lay out your localized text correctly.

Submitting a new localization

Currently, the CotEditor project only accepts new localizations whose provider can maintain them thereafter. When submitting a new localization, please explicitly tell us if you also intend to be a localization maintainer. The standard maintenance process of localization is described in the following subsection.

You have two options for adding a new localization to CotEditor.app. Choose one of them depending on your knowledge and preference:

  • Option 1: Add a new localization in Xcode by yourself and make a pull request (for those who get used to git and Xcode projects):
    • Open CotEditor.xcodeproj in Xcode, go to Project > CotEditor > Info > Localizations, and then add your language to the table. In the Resources group in the project, you can find all strings files (.xcstrings) in both the Localizations and Storyboards subgroups. The new language you added will automatically appear in the catalog list. Select your language and fill each cell of your language column in the table. Note that you don't need to localize the UnicodeBlock.strings file in Packages/Libraries/Sources/CharacterInfo/. It will be done by @1024jp based on Apple's localization data.
    • CotEditor currently uses the String Catalog format (.xcstrings), first introduced in Xcode 15, released in 2023. cf. Localizing and varying text with a string catalog
  • Option 2: Communicate with the maintainer personally and work with a provided localization template (.xcloc file):
    • Send a message to the maintainer (@1024jp) either by creating a new issue on GitHub or by e-mail to ask for the localization template (.xcloc file) for your language. When you receive the .xcloc file, open it in Xcode and fill each cell of your language column in the tables. When finished, send the template file back to the maintainer.

Localization maintenance process

A standard localization update proceeds as follows:

  1. When CotEditor has new strings to be localized, the CotEditor maintainer, @1024jp, creates a new ticket on GitHub Issues and mentions the localization maintainers in it so that they can keep all their localized strings up to date. The ticket includes all strings to be updated and their descriptions, sometimes with screenshots. e.g., #1519.
  2. The localizers either post the localized strings to the thread or make a pull request on GitHub. The maintainers should localize the updated strings within about one week (the shorter period is, of course, welcome, but not required). All the responses must be done on GitHub. Not par email.
  3. The CotEditor maintainer reviews and merges the updates provided by the localizers.

Localization updates may happen once per few months, in general. If a maintainer wants to decline further ongoing maintenance for some reason, it would be kind to express their intentions to the maintainer via email or something. In that case, I will contact the community to find a new maintainer.

Currently, we already have maintainers for:

  • English (UK)
  • Simplified Chinese
  • Traditional Chinese
  • Czech
  • Dutch
  • French
  • German
  • Italian
  • Japanese
  • Portuguese
  • Turkish

Localization for the App Store

The CotEditor project is also asking for localization of description on the Mac App Store. We have a separate repository for it at coteditor/Documents-for-AppStore.

Hints on localization

By localization, use macOS standard terms. It may be helpful to study native Apple applications like TextEdit.app or System Settings to learn how Apple localizes terms in their apps.

Especially, follow the terms of the following applications:

  • Menu item titles in TextEdit.app
  • The Find panel in Pages.app
  • Some setting messages in ScriptEditor.app

Furthermore, we recommend utilizing Apple Localization Terms Glossary for macOS by Kishikawa Katsumi to find macOS-friendly expressions. This service enables us to search in the texts localized by Apple for macOS apps and frameworks. You also need to take care of how Apple treats punctuation characters and symbols. For example, regarding quotation marks, they normally prefer the typographer's ones.

Syntaxes

Adding a new bundled syntax

Put just your new syntax into the /CotEditor/syntaxes/ directory. You don't need to modify the SyntaxMap.json file because it will be automatically generated in the build phase.

The license for the bundled syntaxes must be “Same as CotEditor.”

If the syntax language is relatively minor, we recommend you not to bundle it to CotEditor but to distribute it as an additional syntax in your way, and just add a link to our wiki page.

Themes

We don't accept pull requests adding bundled themes at the moment. You can distribute yours as an additional theme in your way and add a link to our wiki page.

Graphic Resources

We don't accept pull requests for image resources. @1024jp enjoys creating and brushing up on the graphics ;). If you find a graphic resource having some kind of issues to be fixed, please just point it out on the Issues page.

Coding Style Guide

Please follow the style of the existing codes in CotEditor.

  • Respect the existing coding style.
  • Leave reasonable comments.
  • Never omit self except in willSet/didSet.
  • Add final to classes and extension methods by default.
  • Insert a blank line after a class/function statement line. 
    /// say moof.
func moof() {
    
    print("moof")
}
  • Don't declare @IBOutlet properties with !. 
    // OK
@IBOutlet private weak var button: NSButton?

// NG
@IBOutlet private weak var button: NSButton!
  • Write the guard statement in one-line if just returning a simple value. 
    // prefer
guard !foo.isEmpty else { return nil }

// instead of
guard !foo.isEmpty else {
    return nil
}