Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Updated contributing guidelines
  • Loading branch information
alabuzhev committed Oct 22, 2017
1 parent 38d6894 commit 1f1eea4
Show file tree
Hide file tree
Showing 2 changed files with 211 additions and 0 deletions.
104 changes: 104 additions & 0 deletions CONTRIBUTING-RU.md
@@ -0,0 +1,104 @@
### УЧАСТИЕ

> Этот документ поможет вам ознакомиться с нашим процессом разработки.
#### Предложение исправлений

При внесении изменений в исходный код, пожалуйста, следуйте следующим правилам:

1. Каждое изменение должно быть логически завершенным и, по возможности,
минимальным. Это позволит нам быстрее проверить и принять его.
2. Старайтесь придерживаться единообразного стиля оформления кода.
3. Детально опишите, что и зачем ваш код исправляет.
4. Если ваше исправление требует обновления документации (справки,
Энциклопедии и т.п.), не забудьте и ее обновить.
5. Исправления желательно отправлять в виде пулл реквестов в репозиторий
или в виде diff-файлов на наш [багтрекер](http://bugs.farmanager.com)
или [форум](http://forum.farmanager.com/viewforum.php?f=54).
6. Если вы планируете вносить большие исправления или просто желаете находиться
в курсе последних событий в разработке Far'а, подпишитесь на нашу
[рассылку для разработчиков](http://groups.google.com/group/fardev) (fardev@googlegroups.com).
7. Если вы будете присылать нам исправления часто и хорошего качества,
вам будет предоставлен полный доступ к репозиторию, на наше усмотрение.


#### Сборка

1. Для сборки в Visual Studio можно использовать проект для IDE или makefile.
Пример для msbuild & vcxproj:
`msbuild /property:Configuration=Release;platform=x64 far.vcxproj`
Пример для nmake & makefile:
`nmake /f makefile_vc`

2. Для сборки в GCC можно использовать makefile.
Пример для MinGW & makefile:
`mingw32-make -f makefile_gcc`

> Также см. комментарии в makefile_* для дополнительных параметров сборки.
#### Описание изменений - файл `changelog`

1. Все комментарии по внесенным изменениям пишутся в файл `changelog`.
В исходном коде имеет смысл оставлять комментарии только если участок
может быть непонятен для "будущих поколений".
2. Изменения добавляются в начало файла.
3. Каждая запись начинается с шапки вида:
> warp 05.12.2006 01:39:38 +0300 - build 2149
4. Изменениям может не присваиваться билд, например, была косметика или
изменения не в коде.
5. Пример макроса для создания шапки:

```lua
Macro {
area="Editor"; key="Ctrl`"; action = function()
Keys("CtrlHome End CtrlLeft")
build=mf.int(mf.substr(Editor.Value,Editor.RealPos-1))+1;
Keys("CtrlHome")
print(mf.date("name %d.%m0.%Y %H:%M:%S %z - build ")) print(build)
for RCounter=4,1,-1 do Keys("Enter") end
Keys("Up Up 1 . Space")
end;
}
```
#### farversion.m4

1. Этот файл содержит информацию для генерирования версии Far:
* `BUILDTYPE`, строка, определяющая тип сборки:
- '' - пустая строка (релиз)
- `alpha` - альфа версия
- `beta` - бета версия
- `RC` - релиз кандидат
- `ЧтоЛибоДругое` - предназначено для выпуска версий Far, код которых
ещё не вошел в репозиторий, чтоб не путать пользователей и нас.
Вывод версии Far будет выглядеть следующим образом:
`Версия alpha ЧтоЛибоДругое based on build НомерБилда`.
* `MAJOR` - мажорная версия Far (например 3).
* `MINOR` - минорная версия Far (например 0).


#### vbuild.m4

1. Если в файле `vbuild.m4` был изменен номер билда, то после коммита
изменений в репозиторий необходимо запустить `svn_tag_build.bat`.


#### Добавление новых строк в языковые файлы

1. Lng-файлы ренерируются автоматически.
Добавлять изменения надо в `farlang.templ.m4`.
Если вы не знаете, как перевести новые строки на какой-либо язык,
используйте английский вариант с префиксом `upd:`.


#### x64 - обеспечение удачной компиляции для x86 и x64

1. DWORD_PTR, LONG_PTR, etc. применяется вместо DWORD/long/etc. в следующих
случаях:

- нужны там где раньше были int/long/dword/или_любой_не_поинтер_тип_даных
и в него пихали поинтер
- ...
- ...


> Напоминаниям, TODO, примечаниям и т. п. место на [багтрекере](http://bugs.farmanager.com).
107 changes: 107 additions & 0 deletions CONTRIBUTING.md
@@ -0,0 +1,107 @@
### CONTRIBUTING

> Sections below will help you get familiar with our development process.
#### Submitting patches

When you feel comfortable with the code and decide to make your contribution
to the project, please follow those guidelines:

1. One logical change per patch, the smaller the patch the easier it is for us
to review and commit it.
2. Try to keep inline with the overall style of the code.
3. Provide detailed changelog for your patch.
4. If your patch requires updating the documentation (help, Encyclopedia, etc.)
please provide the needed updates.
Please create the patch against the latest code from the repository.
5. Patches should be submitted as pull requests to the repository
or as diff files to our[bugtracker](http://bugs.farmanager.com)
or [forum](http://forum.farmanager.com/viewforum.php?f=54)
6. If you plan to create large patches or want to keep current with the
development of Far Manager, subscribe to the
[Developers mailing list](http://groups.google.com/group/fardeven)
(fardeven@googlegroups.com).
7. Frequent patchers will be eligible for full repository access, by our discretion.


#### Compilation

1. To compile with Visual Studio you can either use the IDE project or makefile.
Example for msbuild & vcxproj:
`msbuild /property:Configuration=Release;platform=x64 far.vcxproj`
Example for nmake & makefile:
`nmake /f makefile_vc`

2. To compile with GCC you can use makefile.
Example for MinGW & makefile:
`mingw32-make -f makefile_gcc`

> Also see comments in makefile_* for additional build parameters.

#### Changelog - `changelog` file

1. All comments on committed changes should be written to the `changelog` file.
You should leave comments in the source code only if you think the code is
not self explanatory and won't be understood by "future generations".
2. Recent changes go on top.
3. Each entry starts with a header of the form:
> warp 05.12.2006 01:39:38 +0300 - build 2149
4. Changes not always require a build increase (i.e. cosmetic or non code
related changes).
5. Sample macro to generate the header:
```lua
Macro {
area="Editor"; key="Ctrl`"; action = function()
Keys("CtrlHome End CtrlLeft")
build=mf.int(mf.substr(Editor.Value,Editor.RealPos-1))+1;
Keys("CtrlHome")
print(mf.date("name %d.%m0.%Y %H:%M:%S %z - build ")) print(build)
for RCounter=4,1,-1 do Keys("Enter") end
Keys("Up Up 1 . Space")
end;
}
```

#### farversion.m4

1. This file contains information used to generate Far version:
* `BUILDTYPE`, a string that defines the build type:
- '' - empty string (release version)
- `alpha` - alpha version
- `beta` - beta version
- `RC` - release candidate
- `AnythingElse` - intended for Far versions which code has not been
committed yet to the repository so we and the users will not be confused.
Far version will look something like that:
`FarVersion alpha AnythingElse based on build BuildNumber`
* `MAJOR` - major Far version (i.e. 3).
* `MINOR` - minor Far version (i.e. 0).


#### vbuild.m4

1. If the build number in `vbuild.m4` was changed then after committing the
changes to the repository you should call `tag_build.bat`.


#### Adding new lines to language files

1. Lng files are generated automatically.
All changes must be made in `farlang.templ.m4`.
If you don't know how to translate your changes to other languages,
use the English version with the `upd:` prefix.


#### x64 - ensuring successful compilation for x86 and x64

1. DWORD_PTR, LONG_PTR, etc. are used instead of DWORD/long/etc. in the
following cases:

- needed where previously int/long/dword/or_any_other_non_pointer_type
were used and a pointer value was assigned to it.
- ...
- ...


> Reminders, todos, notes should go to the [bugtracker](http://bugs.farmanager.com).

0 comments on commit 1f1eea4

Please sign in to comment.