Слияние кода завершено, страница обновится автоматически
Хотите работать над xgen? Отлично! Эта страница содержит информацию о том, как сообщать о проблемах, а также полезные советы и рекомендации для опытных участников открытых проектов. Наконец, убедитесь, что вы ознакомились с нашими правилами поведения перед началом участия.
Поддержка безопасности очень важна для поддерживателей xgen. Если вы обнаружили проблему безопасности, пожалуйста, немедленно сообщите об этом!
Пожалуйста, не создавайте публичный запрос, а отправьте ваш отчет конфиденциально на xuri.me.
Отчеты о безопасности очень ценимы, и мы публично благодарим вас за это. В настоящее время у нас нет программы вознаграждения за обнаружение уязвимостей безопасности, но мы не исключаем возможность её внедрения в будущем.## Сообщение о других проблемах
Отличным способом внести свой вклад в проект является отправка подробного отчета при встрече с проблемой. Мы всегда ценим хорошо составленный, детализированный отчет о баге, и обязательно поблагодарим вас за него!
Убедитесь, что наша база данных проблем не содержит уже аналогичной проблемы или предложения перед тем, как отправить запрос. Если вы найдете совпадение, вы можете использовать кнопку "подписаться", чтобы получать уведомления о новых обновлениях. Не оставляйте случайные "+1" или "У меня тоже есть эта проблема" комментарии, так как они только загромоздят обсуждение и не помогут решению проблемы. Однако, если у вас есть способы воспроизвести проблему или дополнительная информация, которая может помочь в ее решении, пожалуйста, оставьте комментарий.
При отправлении отчетов о проблемах всегда включайте вывод команды go env.
Также включите шаги, необходимые для воспроизведения проблемы, если это возможно и применимо. Эта информация поможет нам быстрее проверить и исправить вашу проблему. При отправке длинных лог-файлов рассмотрите вариант размещения их в виде гиста. Не забудьте удалить чувствительные данные из ваших лог-файлов перед отправкой (вы можете заменить эти части на "REDACTED").
Не уверены, стоит ли отправлять pull request из-за опечатки? Нашли ошибку и знаете, как её исправить? Делайте это! Мы будем признательны за ваш вклад. Любое значительное улучшение должно быть отмечено как GitHub issue до того, как кто-либо начнет работу над ним.
Мы всегда рады принимать pull requests. Мы делаем всё возможное, чтобы быстро их обрабатывать. Если ваш pull request не был принят с первого раза, не расстраивайтесь!
Вы можете предлагать новые дизайны для существующих функций xgen. Вы также можете проектировать совершенно новые функции. Мы очень ценим участников, которые хотят рефакторировать или иначе очищать наш проект.
Мы стараемся поддерживать xgen легким и сфокусированным. Xgen не может делать всё для всех. Это значит, что мы можем решить не внедрять новую функцию. Однако, возможно, есть способ реализовать эту функцию на основе xgen.
Создайте форк репозитория и сделайте изменения на вашем форке в ветке функциональности:
Напишите чистый код. Универсально форматированный код облегчает написание, чтение и обслуживание. Всегда запускайте gofmt -s -w file.go для каждого измененного файла перед тем, как сделать коммит. Большинство редакторов имеют плагины, которые выполняют это автоматически.
Описание pull request должно быть максимально понятным и включать ссылку на все проблемы, которые они решают.
Предложите тесты для ваших изменений. Go имеет отличный встроенный тестовый фреймворк; используйте его! Посмотрите на существующие тесты для вдохновения. Запустите полный набор тестов для вашей ветки перед отправкой pull request.
Набор тестов парсера, находящийся в parser_test.go, работает с двумя источниками входных данных и их ожидаемыми выходными данными:
test, которые включают исходный xsd вместе с ожидаемым выводом для всех языков.data в корне репозитория со следующей структурой:data
├── xsd
├── c
├── go
├── java
├── rs
└── ts
```Оба источника обрабатываются аналогичным образом. Любые файлы `xsd` в подпапке `xsd` используются как входные данные для тестирования.
Для каждого языка, который проверяется, сгенерированный код помещается в папку `<language>/output/`.
Каждая папка `<language>` должна содержать ожидаемый сгенерированный вывод из каждого
входного файла (см. пример с базовым набором в `test`).Чтобы запустить тесты для обоих источников, выполните команду `go test .`. (Не используйте `./...`, что вызовет ошибки сборки из-за ошибок переопределения, так как сгенерированный код и версия отсылки существуют одновременно.)
Полный набор тестов доступен как отдельный [репозиторий](https://github.com/xuri/xsd). Чтобы его запустить, скопируйте верхний уровень содержимого этого репозитория в папку `data` в рабочей копии `xgen`, затем выполните команду `go test .`.
#### Валидность сгенерированного кода
Чтобы проверить, может ли сгенерированный код корректно сериализовать и десериализовать данные, вы можете использовать тест в `xml_test.go`. Эти тестовые случаи требуют, чтобы код был уже сгенерирован, поэтому они работают лучше всего с базовыми тестами, включенными в директорию `test`, которая также используется в качестве ожидаемых выходных данных для `parser_test.go`.Тест также можно модифицировать для прохождения новых тестовых случаев сгенерированного кода в директории `data`
от пользовательских xsd. Однако, поскольку тесты в `data` являются внешними, любые дополнительные
тестовые случаи в `xml_test.go` не следует коммитировать. Чтобы добавить новые XML-тесты для коммита, сначала
добавьте некоторую версию упрощённого файла xsd в `тест` вместе с ожидаемым сгенерированным выходом.
Как только это будет сделано, новый XML-файл можно добавить в `xmlFixtures`, а новый тестовый случай можно добавить,
используя эти два элемента.### Успешные изменения
Перед тем как вносить крупные или значимые изменения, приложите усилия координировать
с владельцами проекта перед отправкой запроса на слияние. Это предотвратит вас от выполнения лишней работы, которая может или может не быть принята.
Крупные запросы на слияние, просто отправленные без предварительной связи, маловероятно будут успешными.
Хотя запросы на слияние являются методологией для представления изменений в коде, изменения
более вероятно будут приняты, если они сопровождаются дополнительной инженерной работой. Хотя мы не определяем это явно, большинство этих целей
достижимы через коммуникацию целей дизайна и последующих решений. Часто бывает полезным сначала сформулировать проблему перед представлением решений. Обычно лучшие методы достижения этой цели включают создание проблемы,
описывающей проблему. Эта проблема может содержать описание проблемы и список требований.
Если предлагается решение, альтернативы должны быть указаны и отсеяны. Даже если критерий отсеивания решения является незначительным, это следует указать.
Более крупные изменения обычно лучше всего работают с документами дизайна. Эти документы сосредоточены на предоставлении контекста дизайну в момент создания функции и могут информировать будущие вклады в документацию.### Сообщения коммитов
Сообщения коммитов должны начинаться с короткого и капитализированного ввода,
написанного в повелительной форме, за которым следует более подробное объяснение,
разделенное пустой строкой от ввода.
Сообщения коммитов должны следовать лучшим практикам, включая объяснение контекста
проблемы и того, как она была решена, включая предостережения или необходимые последующие изменения.
Они должны рассказывать историю изменений и предоставлять читателям понимание того, что привело к этим изменениям.
На практике лучший подход к поддержанию хорошего сообщения коммита заключается в использовании команд `git add -p` и `git commit --amend`, чтобы собрать надежный набор изменений. Это позволяет собирать информацию по мере её становления доступной.
Если вы объединили серию коммитов, не просто отправьте это. Перепишите сообщение коммита, как будто серия коммитов была одним блестящим шагом.
Кроме того, нет необходимости иметь один коммит для запроса слияния, если каждый коммит рассказывает историю. Например, если есть функция, которая требует пакета, имеет смысл иметь этот пакет в отдельном коммите, а затем последующий коммит, который использует его.
Помните, вы рассказываете часть истории с помощью сообщения коммита. Не делайте свою историю странной.### Обзор
Комментарии к обзору кода могут быть добавлены к вашему запросу слияния. Обсудите, выполните предложенные изменения и запушьте дополнительные коммиты в ветку функции. Оставьте комментарий после пуша. Новые коммиты автоматически появятся в запросе слияния, но рецензенты будут уведомлены только при наличии вашего комментария.
Запросы слияний должны быть чисто перефактированы на вершину мастер-ветки без смешивания нескольких веток в запрос слияния.
**Подсказка Git**: Если ваш запрос слияния больше не соединяется чисто, используйте команду `rebase master` в вашей ветке функции, чтобы обновить ваш запрос слияния вместо использования команды `merge master`. Перед тем как создать запрос на слияние, свести ваши коммиты в логические единицы работы с помощью команд `git rebase -i` и `git push -f`. Логическая единица работы — это последовательный набор патчей, который следует рассматривать вместе: например, обновление версии внешней зависимости и использование её нового функционала составляют две отдельные единицы работы. Реализация новой функции и вызов этой функции в другом файле составляют одну логическую единицу работы. Огромное большинство отправляемых работ должно содержать один коммит, поэтому если вы сомневаетесь, сведите всё до одного коммита.После каждого коммита убедитесь, что тест проходит успешно. Включайте изменения в документацию в одном запросе на слияние, чтобы при откате все следы данной функции или исправления были удалены.
Добавьте ссылку на задачу, используя конструкцию `Закрывает #XXXX` или `Исправляет #XXXX`, в коммитах, закрывающих задачу. Включение ссылок автоматически закрывает задачу при слиянии.
Дополнительные руководства см. в разделе [Стиль программирования](#coding-style).
### Утверждение слияния
Поддерживатели проекта xgen используют комментарий "LGTM" (Looks Good To Me) для указания на принятие.
### Подпишите вашу работу
Подпись представляет собой простую строчку в конце объяснения патча. Ваша подпись подтверждает, что вы написали этот патч или имеете право его передать как открытый источник. Правила довольно просты: если вы можете подтвердить ниже (с [developercertificate.org](http://developercertificate.org/)):
```text
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
```(b) Вклад основан на предыдущей работе, которую, по моему мнению, покрывает подходящая лицензия открытого программного обеспечения, и у меня есть право под этой лицензией предоставить эту работу с изменениями, созданными полностью или частично мной, под той же самой лицензией открытого программного обеспечения (если я не имею права предоставлять её под другой лицензией), как указано в файле;
(c) Вклад был предоставлен мне непосредственно другим лицом, которое сертифицировало (a), (b) или (c), и я его не модифицировал.(d) Я понимаю и соглашаюсь с тем, что этот проект и мой вклад являются публичными,
а также то, что запись о моём вкладе (включая всю личную информацию, которую я предоставил вместе с ним, включая мое подтверждение) будет храниться вечно и может быть распространена согласно этому проекту или связанной с ним открытой лицензии программного обеспечения.
Затем вы просто добавляете строку в каждый сообщение коммита git:
```text
Signed-off-by: Ri Xu https://xuri.me
Используйте ваше настоящее имя (извините, псевдонимы или анонимные вклады недопустимы).
Если вы установили свои конфигурационные параметры user.name и user.email в Git, вы можете автоматически подписывать свой коммит с помощью команды git commit -s.
Сначала, все участники имеют три вещи:
Участники часто недооцениваются, потому что их работа трудна для восприятия. Легко оценить действительно крутое и технически продвинутое нововведение. Труднее оценить отсутствие ошибок, медленное но постоянное улучшение стабильности или надёжности процесса выпуска. Но эти вещи отличают хороший проект от великого.Не забывайте: быть участником — это временная инвестиция. Убедитесь, что у вас есть время, чтобы быть доступным. Вы не обязаны быть участником, чтобы делать разницу в проекте!
Если вы хотите стать участником, свяжитесь с xuri.me и представьтесь.
Мы хотим, чтобы сообщество было замечательным, развивающимся и взаимодействующим. Мы нуждаемся в вашей помощи, чтобы поддерживать это состояние. Для этого мы разработали некоторые общие правила поведения для всего сообщества:
Будьте доброжелательны: Будьте учтивыми, уважительными и вежливыми по отношению к остальным членам сообщества; никакое региональное, расовое, гендерное или любое другое унижение не будет допускаться. Нам больше нравятся добродушные люди, чем злобные!
Поощряйте разнообразие и участие: Делайте всех чувствовать себя приветливо в нашем сообществе, независимо от их происхождения и степени их вклада, и делайте всё возможное, чтобы поощрять участие в нашем сообществе.
Держите всё в рамках закона: В общих чертах, не позволяйте нам попасть в неприятности. Поддерживайте только контент, который принадлежит вам, не распространяйте конфиденциальную информацию и не нарушайте закон.* Оставайтесь на тему: Убедитесь, что вы публикуете сообщения в правильном канале и избегаете отклонений от темы. При обновлении проблемы или ответе на электронное письмо помните, что ваши действия могут затрагивать большое количество людей. Пожалуйста, имейте это в виду перед отправкой обновлений. Также помните, что никто не любит спам.* Не отправляйте электронные письма поддержке: Нет необходимости отправлять электронные письма поддержке с просьбой рассмотреть проблему или просмотреть запрос на слияние. Вместо этого используйте упоминания GitHub для обращения к поддержке для проверки запроса на слияние, предложения или проблемы.
Цель данного раздела не в том, чтобы находить возможности для наказания участников, но мы должны иметь справедливый способ взаимодействия с участниками, делающими наше сообщество менее комфортным.
Первое нарушение: Мы дадим вам дружелюбное, но публичное напоминание о том, что ваше поведение противоречит нашим правилам.
Второе нарушение: Мы отправим вам личное сообщение с предупреждением, что повторные нарушения будут приводить к удалению из сообщества.
Третье нарушение: В зависимости от серьезности нарушения, может потребоваться удаление или бана вашего аккаунта.
Примечания:
Очевидные спамеры заблокируются после первого нарушения. Если бы мы не делали этого, то спам был бы повсюду.
Наши правила прощают нарушителей после шестимесячного периода добросовестного поведения, и мы не будем держать зло за спиной.
Люди, совершившие мелкие нарушения, получат образование вместо применения строгого подхода трех замечаний.* Правила одинаково применяются ко всем членам сообщества, вне зависимости от количества ваших вкладов.
Грубые нарушения угрожающего, агрессивного, разрушительного или незаконного характера будут немедленно решены и не подвергаются процедуре трёх замечаний или прощения.
Для обращения о нарушениях или апелляций свяжитесь с xuri.me. В случае апелляций, мы знаем, что ошибки случаются, и будем работать вместе с вами, чтобы найти справедливое решение при недопонимании.
Если не указано иное, мы следуем всем правилам программирования, принятым в сообществе Go. Хотя некоторые из этих стандартов могут казаться произвольными, они каким-то образом приводят к надёжному и последовательному коду. Возможно, что база кода в настоящее время не соответствует этим рекомендациям. Мы не ищем огромного пулл-реквеста, который бы исправил это, так как это противоречит духу этих рекомендаций. Все новые вклады должны стремиться очистить и сделать базу кода лучше, чем они её оставили. Разумеется, применяйте своё лучшее суждение. Цель здесь — сделать базу кода легче для людей навигировать и понимать. Всегда помните об этом, когда направляете других к соблюдению этих правил.
Правила:1. Все коды должны быть отформатированы с помощью gofmt -s.
2. Все коды должны проходить уровни по умолчанию проверки
golint.
3. Все коды должны следовать рекомендациям, описанным в Effective
Go и Go Code Review
Comments.
4. Комментируйте код. Объясняйте нам, почему, история и контекст.
5. Документируйте все объявления и методы, даже приватные. Опишите
ожидания, ограничения и все остальное, что может быть важным. Если тип
экспортирован, наличие комментариев обеспечит его готовность.
6. Длина имени переменной должна быть пропорциональна её контексту и не
должна быть длиннее. noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo.
На практике короткие методы будут иметь короткие имена переменных, а глобальные — более длинные.
7. Никаких подчеркиваний в названиях пакетов. Если вам нужен составной
название, сделайте шаг назад и переоцените необходимость такого названия. Если вы всё ещё считаете, что вам нужен составной название, удалите подчеркивание.
8. Нет пакетов utils или helpers. Если функция недостаточно общего характера, чтобы заслуживать своего собственного пакета, она не была написана достаточно широко, чтобы стать частью пакета utils. Просто оставьте её невы导出的，并且有良好的文档记录。
9. Все тесты должны выполняться через go test, без использования внешних инструментов. Нет, мы не нуждаемся в другом фреймворке для юнит-тестирования.Ассерты можно использовать, если они действительно предоставляют增值。
10. Хотя мы выше называли эти "правилами", на самом деле они являются лишь руководящими принципами. Теперь, когда вы прочитали все правила, вы знаете это.
Корректный вариант:
Ассерты можно использовать, если они действительно предоставляют истинное увеличение ценности. 10. Хотя мы выше называли эти "правилами", на самом деле они являются лишь рекомендациями. Теперь, когда вы прочитали все правила, вы знаете это.Если вы сталкиваетесь с трудностями при входе в состояние, привычное для языка Go, мы рекомендуем вам прочитать Effective Go. Go блог также является отличным источником информации. Употребление Kool-Aid легче, чем просто жажда.
CodeLingo автоматически проверяет каждый pull request против руководств из Effective Go и Комментариев к проверке кода.
Каждый пакет должен содержать комментарий к пакету, который представляет собой блочный комментарий перед оператором пакета. Для мультифайловых пакетов комментарий к пакету требуется только в одном файле, и любой будет подходящим. Комментарий к пакету должен представлять пакет и предоставлять информацию, относящуюся ко всему пакету. Он будет первым на странице godoc и должен подготовить пользователя к более детальной документации, которая следует за ним.
Согласно соглашению, интерфейсы с одним методом должны называться именем метода плюс суффиксом "-er" или аналогичной модификацией для создания агента: Reader, Writer, Formatter, CloseNotifier и так далее.Существует множество таких имен, и полезно придерживаться их и функций, которые они охватывают. Имена Read, Write, Close, Flush, String и так далее имеют канонические сигнатуры и значения. Чтобы избежать путаницы, не давайте своему методу одно из этих имен, если его сигнатура и значение не совпадают. Обратно, если ваш тип реализует метод с тем же значением, что и метод известного типа, дайте ему то же имя и сигнатуру; называйте свой метод конвертации строки String, а не ToString.### Избегайте аннотаций в комментариях
Комментарии не требуют дополнительного форматирования, такого как баннеры звездочек. Генерируемый вывод может даже не представляться в фиксированном шрифте, поэтому не полагайтесь на отступы для выравнивания — godoc, как и gofmt, берут это на себя. Комментарии являются неинтерпретированным простым текстом, поэтому HTML и другие аннотации, такие как this, будут воспроизводиться буквально и не должны использоваться. Одной из корректировок godoc является отображение отступленного текста в фиксированном шрифте, подходящего для фрагментов программы.
Комментарий к пакету fmt использует это хорошо.
Документальные комментарии работают лучше всего как полные предложения, что позволяет широкому спектру автоматических презентаций. Первая фраза должна быть однословное описание, которое начинается с имени, объявляемого.### Хорошее название пакета
Полезно, если все пользователи пакета могут использовать одно и то же имя для обращения к его содержимому, что подразумевает, что название пакета должно быть хорошим: коротким, лаконичным и выразительным. По соглашению, пакетам дают названия в нижнем регистре, состоящие из одного слова; нет необходимости использовать подчеркивания или MixedCaps. В пользу краткости следует склоняться, так как каждый пользователь вашего пакета будет набирать это имя. И не стоит беспокоиться заранее о коллизиях. Название пакета является только основным именем для импорта; оно не обязательно должно быть уникальным для всех исходных кодов, и в редком случае возникновения коллизий импортирующий пакет может выбрать другое имя для использования локально. Во всяком случае, путаница редка, поскольку имя файла в импорте определяет именно тот пакет, который используется.### Избегайте Переименования Импортов
Избегайте переименования импортов, кроме случаев, когда требуется избежать коллизий имен; хорошие названия пакетов не требуют переименования. В случае коллизии предпочитайте переименование самого локального или проектно-специфического импорта.
Значения типа context.Context передают сведения безопасности, информацию трассировки, сроки действия и сигналы отмены через границы API и процессов. Программы на Go передают контексты явно по всей цепочке вызова функций от входящих RPC и HTTP-запросов до исходящих запросов.
Большинство функций, использующих контекст, должны принимать его в качестве первого параметра.
Не игнорируйте ошибки с помощью _ переменных. Если функция возвращает ошибку, проверьте её, чтобы удостовериться, что функция выполнилась успешно. Обработайте ошибку, верните её или, в действительно исключительной ситуации, выбросьте панику.
fmt.Errorf("что-то плохое"), а не fmt.Errorf("Что-то плохое"), чтобы сообщение log.Printf("Чтение %s: %v", filename, err) формировалось без лишней прописной буквы внутри сообщения. Это правило не применяется к логированию, которое является по умолчанию ориентировано на строки и не объединено внутри других сообщений.### Используйте Crypto RandНе используйте пакет math/rand для генерации ключей, даже временных. Без инициализатора, генератор полностью предсказуем. При использовании времени в виде time.Nanosecond(), количество энтропии ограничено несколькими битами. Вместо этого используйте crypto/rand.Reader, и если вам нужна текстовая форма, печатайте в шестнадцатеричном или base64 форматах.
Вы можете оставить комментарий после Вход в систему
Неприемлемый контент может быть отображен здесь и не будет показан на странице. Вы можете проверить и изменить его с помощью соответствующей функции редактирования.
Если вы подтверждаете, что содержание не содержит непристойной лексики/перенаправления на рекламу/насилия/вульгарной порнографии/нарушений/пиратства/ложного/незначительного или незаконного контента, связанного с национальными законами и предписаниями, вы можете нажать «Отправить» для подачи апелляции, и мы обработаем ее как можно скорее.
Опубликовать ( 0 )