diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 0ca918ab..4bf68227 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,8 +1,15 @@ +  [Introduction](#contributing-to-cockatrice) | [Code Style Guide](#code-style-guide) | [Translations](#translations) | [Release Management](#release-management) + +---- + +
+ # Contributing to Cockatrice # First off, thanks for taking the time to contribute to our project! 🎉 ❤ ️✨ The following is a set of guidelines for contributing to Cockatrice. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. + # Recommended Setups # For those developers who like the Linux or MacOS environment, many of our developers like working with a nifty program called [CLion](https://www.jetbrains.com/clion/). The program's a great asset and one of the best tools you'll find on these systems, but you're welcomed to use any IDE you most enjoy. @@ -11,7 +18,8 @@ Developers who like Windows development tend to find [Visual Studio](https://www If you have any questions on IDEs, feel free to chat with us on [Gitter](https://gitter.im/Cockatrice/Cockatrice) and we would love to help answer your questions! -# Style Guide # + +# Code Style Guide # ### Compatibility ### @@ -166,19 +174,23 @@ Any change to the `proto` file should be taken with caution and tested intensive You can find more information on how we use Protobuf on [our wiki!](https://github.com/Cockatrice/Cockatrice/wiki/Client-server-protocol) -### Translations: introduction ### -Basic workflow for translations: - 1. developer adds a `tr("foo")` string in the code; - 2. every few days, a maintainer updates the `*_en.ts files` adding the new strings; +# Translations # + +**Basic workflow for translations:** + 1. Developer adds a `tr("foo")` string in the code; + 2. Every few days, a maintainer updates the `*_en.ts files` with the new strings; 3. Transifex picks up the new files from github every 24 hours; - 4. translators translate the new untraslated strings on Transifex; - 5. before a release, a maintainer fetches the updated translations from Transifex. + 4. Translators translate the new untraslated strings on Transifex; + 5. Before a release, a maintainer fetches the updated translations from Transifex. ### Translations (for developers) ### +**Step 1: Adding translatable strings to the code (`tr("foo")`)** + All the user-interface strings inside Cockatrice's source code must be written in -english language. Translations to other languages are managed using [Transifex](https://www.transifex.com/projects/p/cockatrice/). +english language.
+Translations to other languages are managed using [Transifex](https://www.transifex.com/projects/p/cockatrice/). If you're about to propose a change that adds or modifies any translatable string in the code, you don't need to take care of adding the new strings to the @@ -189,7 +201,7 @@ translators on Transifex. ### Translations (for maintainers) ### -#### Step 2: updating *_en.ts files #### +**Step 2: Updating `*_en.ts` files with new strings** When new translatable strings have been added to the code, it would be nice to make them available to translators on Transifex. Every few days, or when a lot @@ -219,12 +231,14 @@ It's now suggested to disable the parameter using: ```sh cmake .. -DUPDATE_TRANSLATIONS=OFF ``` -Now you are ready to propose your change. Once your change gets merged, -Transifex will pick up the modified files automatically (checks every 24 hours) -and update the interface where translators will be able to translate the new -strings. +Now you are ready to propose your change. -#### Step 5: fetch new translations from Transifex #### +**Step 3: Automatic pushing to Transifex** + +Once your change gets merged, Transifex will pick up the modified files automatically (checks every 24 hours) +and update the interface where translators will be able to translate the new strings. + +**Step 5: Fetching new translations from Transifex** Before rushing out a new release, it would be nice to fetch the most up to date translations from Transifex and commit them into the Cockatrice source code. @@ -240,13 +254,18 @@ from Transifex to the source code and vice versa. ### Translations (for translators) ### +**Step 4: Editing translations at Transifex** + Please have a look at the specific [FAQ for translators](https://github.com/Cockatrice/Cockatrice/wiki/Translation-FAQ). -### Publish A New Development Snapshot -TravisCI and Appveyor have been configured to upload files to GitHub whenever a tag is pushed. Usually, tags are created through publishing a full release, but there's a way around that. +# Release Management # -To trigger TravisCI and Appveyor, simply do the following: +### Publish A New Development Snapshot ### + +Travis and AppVeyor have been configured to upload files to GitHub Releases whenever a tag is pushed. Usually, tags are created through publishing a release, but there's a way around that. + +To trigger Travis and AppVeyor, simply do the following: ```bash cd $COCKATRICE_REPO git checkout master @@ -260,12 +279,12 @@ You should define the variables as such: upstream - git@github.com:Cockatrice/Cockatrice.git $COCKATRICE_REPO - /Location/of/repository/cockatrice.git $TAG_NAME - - If full release, YYYY-MM-DD-Release-MAJ.MIN.PATCH - - If dev snapshot, YYYY-MM-DD-Development-MAJ.MIN.PATCH-beta.X + - If stable release, YYYY-MM-DD-Release-MAJ.MIN.PATCH + - If beta release, YYYY-MM-DD-Development-MAJ.MIN.PATCH-beta.X - MAJ.MIN.PATCH will be the NEXT release version ``` -This will cause a tag release to be established on the GitHub repository, which will then lead to the upload of binaries. If you use this method, the tags (releases) that you create will be marked as a "pre-release" build. The `/latest` URL will not be impacted (For stable branch downloads) so that's good. +This will cause a tag release to be established on the GitHub repository, which will then lead to the upload of binaries. If you use this method, the tags (releases) that you create will be marked as a "Pre-release". The `/latest` URL will not be impacted (for stable release downloads) so that's good. If you accidentally push a tag incorrectly (the tag is outdated, you didn't pull in the latest branch accidentally, you named the tag wrong, etc.) you can revoke the tag by doing the following: ```bash @@ -273,11 +292,11 @@ git push --delete upstream $TAG_NAME git tag -d $TAG_NAME ``` -**NOTE:** Unfortunately, due to the method of how TravisCI and Appveyor work, to publish a full release you will need to make a copy of the release notes locally and then paste them into the GitHub GUI once the binaries have been uploaded. These build sites will automatically change the name of the release (to $TAG_NAME from whatever it was), the status of the release (to pre-release), and the body (to "Dev build of Cockatrice"). +**NOTE:** Unfortunately, due to the method of how Travis and AppVeyor work, to publish a full release you will need to make a copy of the release notes locally and then paste them into the GitHub GUI once the binaries have been uploaded by them. These CI services will automatically overwrite the name of the release (to "Cockatrice $TAG_NAME"), the status of the release (to "Pre-release"), and the release body (to "Beta build of Cockatrice"). **NOTE 2:** In the first lines of https://github.com/Cockatrice/Cockatrice/blob/master/CMakeLists.txt there's an hardcoded version number used when compiling custom (not tagged) versions. While on tagged versions these numbers are overriden by the version numbers coming from the tag title, it's a good practice to keep them aligned with the real ones. The preferred flow of operations is: * just before a release, update the version number in CMakeLists.txt to "next release version"; * tag the release following the previously described syntax in order to get it built by CI; * wait for CI to upload the binaries, double check if everything is in order - * after the release is complete, update the version number again to "next development version", typically increasing `PROJECT_VERSION_PATCH` by one. + * after the release is complete, update the version number again to "next beta version", typically increasing `PROJECT_VERSION_PATCH` by one.