diff --git a/FAQ.md b/FAQ.md index da3715e..b123e0f 100644 --- a/FAQ.md +++ b/FAQ.md @@ -3,9 +3,10 @@ A list of frequently asked questions related to common issues: 1. [How to open a new issue](https://github.com/notepad-plus-plus/notepad-plus-plus/wiki/FAQ#how-to-open-a-new-issue) - 2. [Outdated configuration files](https://github.com/notepad-plus-plus/notepad-plus-plus/wiki/FAQ#outdated-configuration-files) - 2. [Incorrect character rendering](https://github.com/notepad-plus-plus/notepad-plus-plus/wiki/FAQ#incorrect-character-rendering) - 4. [Support for systems other than the MS Windows family](https://github.com/notepad-plus-plus/notepad-plus-plus/wiki/FAQ#support-for-systems-other-than-the-ms-windows-family) + 2. [How to create a non-blocking Pull Request (PR)](https://github.com/notepad-plus-plus/notepad-plus-plus/wiki/FAQ/_edit#how-to-create-a-non-blocking-pull-request-pr) + 3. [Outdated configuration files](https://github.com/notepad-plus-plus/notepad-plus-plus/wiki/FAQ#outdated-configuration-files) + 4. [Incorrect character rendering](https://github.com/notepad-plus-plus/notepad-plus-plus/wiki/FAQ#incorrect-character-rendering) + 5. [Support for systems other than the MS Windows family](https://github.com/notepad-plus-plus/notepad-plus-plus/wiki/FAQ#support-for-systems-other-than-the-ms-windows-family) ## How to open a new issue @@ -15,6 +16,45 @@ Before you open a new issue to report a bug, try to follow the rules below: 3. When you open a new issue you will receive an initial template to fill out. Try to follow it, in particular, never skip `Debug Information` section. 4. For issue related to text or code put it in a form that can be copied (use delimiters [\`\`\` Your code here \`\`\`](https://docs.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks) or [attach a file](https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/attaching-files)). The print screen should only be an addition, not a source for reproducing your problem! +## How to create a non-blocking Pull Request (PR) + +By default each commit in PR runs a build that contains 10 jobs with full compilation and some tests (mainly syntax check for XML files). The entire process can take up to ~1.5 h. + +If only XML files (such as localization, themes or auto-completion) have been modified in a given PR, then the entire build time can be optimized by explicitly adding the `[xml]` flag at the beginning of the commit title. For example: +``` +[xml] Update English localization + +[xml] Update Bespin.xml theme + +[xml] Update javascript.xml auto-completion +``` +This cause that commit will runs a build with one job `Win32/Debug`, which will only perform XML validation. This process takes ~1 min. + +If the `[xml]` flag is not explicitly specified in the commit title and only XML files was modified then some build time optimization will be performed implicitly anyway, but it's not perfect (takes ~14 min). + +**For this reason it's encouraged to use `[xml]` flag whenever only XML files have been modified.** + +*The above guidelines also apply to other files that don't require any compilation or test (currently for `md`, `txt`, or `log`). If a given PR modifies only such files then please use same `[xml]` flag at the beginning of the commit title. + +### Other available flags + +There are other flags that may be useful when working on a given PR. They should only be used as an intermediate step between different commits (for testing purposes). The last commit in a given PR should pass the build without any flag or with using only `[XML]` flag. + +`[skip ci]` or `[ci skip]` or `[skip appveyor]` - flags offered directly from AppVeyor, which completely omit the entire build. + +`[force xml]` - regardless of changed files 10 jobs will be run, where 9 jobs will be canceled after running, only `Win32/Debug` perform XML validation (without compilation). + +`[xml][force xml]` - regardless of changed files the combination of these two flags will run one job `Win32/Debug`, which will perform XML validation (without compilation). + +`[force nowork]` or `[xml][force nowork]` - analogously to the above, but job `Win32/Debug` does nothing (will be canceled). + +`[xml][force compile]` - if files requiring compilation have been changed (like `cpp`) the combination of these two flags allow us to run only one job `Win32/Debug` with standard compilation and perform all test. + +If we need to use some of the above flags, but without making any changes to the last commit, then an empty commit can be done: +``` +git commit --allow-empty -m "[xml][force compile] Give me only Win32/Debug build" +``` + ## Outdated configuration files Some problems may arise because of outdated configuration files. The easiest way to determine this case is repeat the problem in the latest portable version ([instruction](https://github.com/notepad-plus-plus/notepad-plus-plus/wiki/Testing)). If everything works fine in the portable version, you should locate your configuration files and update them manually. Depending on the situation different `.xml` files should be update (check the manual for [configuration files details](https://npp-user-manual.org/docs/config-files/)).