Вклад в VFS для Git

Спасибо, что нашли время внести свой вклад!

Рекомендации

• Кодекс поведения
• Обзоры дизайна
• Код для конкретной платформы
• Трассировка и ведение журнала
• Обработка ошибок
• Фоновые потоки
• Соглашения о кодировании
• Тестирование

Кодекс поведения

Этот проект принял Кодекс поведения с открытым исходным кодом Microsoft. Для получения дополнительной информации см. Часто задаваемые вопросы о кодексе поведения или свяжитесь с opencode@microsoft.com, если у вас есть дополнительные вопросы или комментарии.

Обзоры дизайна

Архитектурные изменения и новые функции должны начинаться с обзора дизайна. Легче и меньше времени тратится на то, чтобы учесть отзывы на этом этапе.

Процесс обзора дизайна выглядит следующим образом:

1. Создайте запрос на вытягивание, который содержит документ проектирования в формате Markdown (.md) для предлагаемого изменения. Назначьте запросу на вытягивание метку design-doc.
2. Используйте запрос на вытягивание для обратной связи по дизайну и для итерации по дизайну.
3. Как только дизайн будет одобрен, создайте новую проблему с описанием, которое включает окончательный документ проектирования. Добавьте ссылку на запрос на вытягивание, который использовался для обсуждения.
4. Закройте (без слияния!) запрос на вытягивание, использованный для обсуждения дизайна.

Код для конкретной платформы

• Предпочитайте кросс-платформенный код коду для конкретной платформы

Кросс-платформенный код легче использовать повторно. Повторное использование кода уменьшает объем кода, который необходимо написать, протестировать и поддерживать.

• Код для конкретной платформы и только код для конкретной платформы должен идти в GVFSPlatform

Когда требуется код для конкретной платформы, он должен быть помещен в GVFSPlatform или одну из платформ, которые он содержит (например, IKernelDriver)

Трассировка и ведение журнала

• Уровень ведения журнала «Ошибка» зарезервирован для ошибок, не подлежащих повторной попытке, которые приводят к сбоям ввода-вывода или завершению работы процесса VFS4G

Ожидание наших клиентов заключается в том, что когда VFS4G регистрирует сообщение уровня «Ошибка» в своем файле журнала, либо: * VFS4G пришлось неожиданно завершить работу * VFS4G столкнулся с проблемой, достаточно серьезной, чтобы пользовательский инициированный ввод-вывод завершился ошибкой.

• Регистрируйте полные стеки исключений

Полные стеки исключений (т. е. Exception.ToString) предоставляют больше деталей, чем одно сообщение об исключении (Exception.Message). Полные стеки исключений упрощают поиск первопричины проблем.

• Не отображайте полные стеки исключений пользователям

Стеки вызовов исключений обычно не являются полезными для пользователя. Пользователи часто (иногда ошибочно) предполагают, что VFS4G вышел из строя, когда им показывают полный стек. Полный стек должен быть включен в журналы VFS4G, но не должен отображаться как часть сообщения об ошибке, предоставляемого пользователю.

• Включайте соответствующие детали при регистрации исключений

Иногда одного стека вызовов исключения недостаточно, чтобы найти первопричину сбоев в VFS4G. При перехвате (или выбрасывании) исключений регистрируйте соответствующие детали, которые помогут диагностировать проблему. Как правило, чем ближе исключение поймано к тому месту, где оно было выброшено, тем больше будет соответствующих деталей для регистрации.

Пример:

catch (Exception e)
{
  EventMetadata metadata = new EventMetadata();
  metadata.Add("Area", "Mount");
  metadata.Add(nameof(enlistmentHookPath), enlistmentHookPath);
  metadata.Add(nameof(installedHookPath), installedHookPath);
  metadata.Add("Exception", e.ToString());
  context.Tracer.RelatedError(metadata, $"Failed to compare {hook.Name} version");
}

Обработка ошибок

• Быстрое завершение работы: ошибка или исключение, которое может привести к потере данных или повреждению, должно немедленно завершить работу VFS4G

Предотвращение потери данных и повреждения репозитория имеет решающее значение. Если возникает ошибка или исключение, которые могут привести к потере данных, лучше завершить работу VFS4G, чем оставить репозиторий смонтированным и рискнуть повредить его.

• Не перехватывайте исключения, указывающие на ошибку программиста (например, ArgumentNullException)

Любые исключения, которые... Ошибки программиста (например, ArgumentNullException) должны быть обнаружены как можно раньше в процессе разработки. Следует избегать использования операторов catch, которые могут скрывать такие ошибки (например, catch(Exception)).

Исключение составляет только случай необработанных исключений в фоновых потоках.

• Не используйте исключения для нормального потока управления.

Предпочитайте писать код, который не генерирует исключения. Например, шаблон TryXXX позволяет избежать затрат на производительность, связанных с использованием исключений. Кроме того, VFS4G обычно должен точно знать, где возникают ошибки, и обрабатывать их там. Шаблон TryXXX помогает обеспечить обработку ошибок таким образом.

Пример: обрабатывайте ошибки там, где они возникают (хорошо):

bool TryDoWorkOnDisk(string fileContents, out string error)
{
    if (!TryCreateReadConfig())
    {
        error = "Не удалось прочитать файл конфигурации";
        return false;
    }

    if (!TryCreateTempFile(fileContents))
    {
        error = "Не удалось создать временный файл";
        return false;
    }

    if (!TryRenameTempFile())
    {
        error = "Не удалось переименовать временный файл";
        if (!TryDeleteTempFile())
        {
            error += ", и не удалось очистить временный файл";
        }

        return false;
    }

    error = null;
    return true;
}

Пример: обрабатывайте ошибки в catch без знания, откуда они взялись (плохо):

bool TryDoWorkOnDisk(string fileContents, out string error)
{
    try
    {
        CreateReadConfig();
        CreateTempFile(fileContents);
        RenameTempFile();
    }
    catch (Exception ex) when (ex is IOException || ex is UnauthorizedAccessException)
    {
        error = "Что-то пошло не так при работе с диском";

        try
        {
            if (TempFileExists())
            {
                DeleteTempFile();
            }
        }
        catch (Exception e) when (e is IOException || e is UnauthorizedAccessException)
        {
            error += ", и не удалось очистить временный файл";
        }

        return false;
    }

    error = null;
    return true;
}

• Предоставляйте пользователю сообщения, побуждающие к действию, когда это возможно.

Не говорите пользователю, что пошло не так. Помогите пользователю решить проблему.

Пример:

«Вы можете указать --hydrate только если репозиторий смонтирован. Запустите 'gvfs mount' и попробуйте снова».

Фоновые потоки

• Избегайте использования пула потоков (и избегайте использования async).

HttpRequestor.SendRequest делает блокирующий вызов для HttpClient.SendAsync. Этот блокирующий вызов потребляет поток из управляемого пула потоков. До тех пор, пока эта конструкция не изменится, остальная часть VFS4G должна избегать использования пула потоков, кроме случаев крайней необходимости. Если пул потоков необходим, любые длительные задачи следует перенести в отдельный поток, управляемый самим VFS4G (см. GitMaintenanceQueue для примера).

Длительная или блокирующая работа, запланированная в управляемом пуле потоков, может помешать нормальной работе VFS4G. Например, это может помешать своевременному скачиванию размеров файлов, свободных объектов или содержимого файлов.

• Ловите все исключения в длительных задачах и фоновых потоках.

Оберните весь код, работающий в фоновом потоке, в обработчик верхнего уровня try/catch(Exception). Любые исключения, пойманные этим обработчиком, должны регистрироваться, а затем VFS4G должен принудительно завершать работу с помощью Environment.Exit. Небезопасно позволять VFS4G продолжать работу после того, как необработанное исключение остановило фоновый поток или длительную задачу. Тестирование показало, что Environment.Exit последовательно завершает процесс монтирования VFS4G независимо от того, как запускаются фоновые потоки (например, собственный поток, new Thread(), Task.Factory.StartNew()).

Пример этого шаблона можно увидеть в...