This is an automated email from the ASF dual-hosted git repository.
wilfreds pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/yunikorn-site.git
The following commit(s) were added to refs/heads/master by this push:
new 53dc815 [YUNIKORN-1048] Update how to contribute doc (#146)
53dc815 is described below
commit 53dc8157b914ef7aa2779f37efea426d61fdf208
Author: Wilfred Spiegelenburg <[email protected]>
AuthorDate: Fri Apr 1 02:29:53 2022 +1100
[YUNIKORN-1048] Update how to contribute doc (#146)
Moved reporting a security issue into reporting_issues for both
languages.
Extended and clarified the contribution doc.
Requires updates made in YUNIKORN-371 and YUNIKORN-179
Closes: #146
Signed-off-by: Wilfred Spiegelenburg <[email protected]>
---
.../community/how_to_contribute.md | 8 +-
.../community/reporting_issues.md | 41 +++---
src/pages/community/how_to_contribute.md | 160 ++++++++++++++++++---
src/pages/community/reporting_issues.md | 58 ++++----
4 files changed, 199 insertions(+), 68 deletions(-)
diff --git
a/i18n/zh-cn/docusaurus-plugin-content-pages/community/how_to_contribute.md
b/i18n/zh-cn/docusaurus-plugin-content-pages/community/how_to_contribute.md
index 060a696..968694a 100644
--- a/i18n/zh-cn/docusaurus-plugin-content-pages/community/how_to_contribute.md
+++ b/i18n/zh-cn/docusaurus-plugin-content-pages/community/how_to_contribute.md
@@ -27,7 +27,7 @@ under the License.
YuniKorn 使用：
* JIRA 用于问题跟踪。
* GitHub 用于 Pull Requests(以后简称拉取请求)来管理代码审查和更改本身。
-* MarkDown 用于文档的源代码树。
+* Markdown 文档，版本化并存储在网站存储库中。
## 发现问题
我们使用 JIRA 问题库来跟踪该项目的错误。
@@ -94,12 +94,6 @@ YuniKorn 使用：
提交消息必须在第一行包含 JIRA，并且应该包含 `Closes #1`，这样一个提交将自动关闭 PR。
JIRA 不会自动关闭。
-## 报告安全问题
-YuniKorn 社区非常关心安全问题，并将积极解决任何安全问题作为重中之重。
-我们遵循 Apache 安全指南来处理安全问题，请参阅 Apache 文档关于
[处理安全问题](https://www.apache.org/security/)。
-如果您发现任何安全问题，请将漏洞报告发送至 [email protected]，YuniKorn 安全团队将立即评估问题并与报告者一起制定修复计划。
-在与安全团队合作之前，请不要将问题透露给任何公共论坛。
-
## 如果仍有问题？
如果您不确定某些事情，请尝试遵循现有代码库的样式。
看看代码中是否有其他例子做类似的事情。
diff --git
a/i18n/zh-cn/docusaurus-plugin-content-pages/community/reporting_issues.md
b/i18n/zh-cn/docusaurus-plugin-content-pages/community/reporting_issues.md
index afb0f7c..76ad350 100644
--- a/i18n/zh-cn/docusaurus-plugin-content-pages/community/reporting_issues.md
+++ b/i18n/zh-cn/docusaurus-plugin-content-pages/community/reporting_issues.md
@@ -24,15 +24,20 @@ under the License.
# 报告问题
+## 报告安全问题
+YuniKorn 社区非常关心安全问题，并将积极解决任何安全问题作为重中之重。
+我们遵循 Apache 安全指南来处理安全问题，请参阅 Apache 文档关于
[处理安全问题](https://www.apache.org/security/)。
+如果您发现任何安全问题，请将漏洞报告发送至 [email protected]，YuniKorn 安全团队将立即评估问题并与报告者一起制定修复计划。
+在与安全团队合作之前，请不要将问题透露给任何公共论坛。
+
## 对于 YuniKorn 用户
如果您对 YuniKorn 操作有任何疑问，请遵循以下指南：
如果您在设置、配置或在其他不符合您期望的行为方面遇到问题时，请加入用户邮件列表并在该论坛中提问。
-有关邮件列表的信息，请参见 [YuniKorn 网页](https://yunikorn.apache.org)。
+有关邮件列表的信息，请参见 [YuniKorn
网页](https://yunikorn.apache.org/zh-cn/community/get_involved)。
您也可以向 YuniKorn slack 频道寻求帮助，查看网页了解如何加入的详细信息。
如果您在代码或文档中有需要修复的错误，请按照下面的 [归档 JIRA](#为-YuniKorn-问题提交-JIRA) 中的步骤进行操作。
-## 对于 YuniKorn 开发人员
Apache YuniKorn 项目使用 JIRA 来跟踪所有问题。
这些包括：
1. 添加新功能
@@ -56,24 +61,28 @@ Apache YuniKorn 项目使用 JIRA 来跟踪所有问题。
如果您已将问题分到特定组件，请设置组件字段：
-| 组件 | 描述 |
-|-----------|-------------|
-| build| 项目构建、构建脚本和 git 问题 |
-| core - cache | 核心调度器缓存 |
-| core - common | 核心调度器的公共代码，如资源 |
-| core - scheduler | 核心调度问题 |
-| documentation | 文档修复和增强 |
-| scheduler-interface | 调度器接口规范 |
-| security | 安全相关问题 |
-| shim - kubernetes | K8shim 问题 |
-| shim - yarn | Hadoop YARN shim 问题 |
-| test - smoke | 冒烟测试失败 |
-| test - unit | 单元测试失败 |
-| webapp | 调度器的 Web UI |
+| 组件 | 描述 |
+|---------------------|---------------------|
+| build | 项目构建、构建脚本和 git 问题 |
+| core - common | 核心调度器的公共代码，如资源 |
+| core - scheduler | 核心调度问题 |
+| documentation | 文档修复和增强 |
+| scheduler-interface | 调度器接口规范 |
+| security | 安全相关问题（加密、授权和身份验证） |
+| shim - kubernetes | K8shim 问题 |
+| shim - yarn | Hadoop YARN shim 问题 |
+| test - smoke | 冒烟测试失败 |
+| test - unit | 单元测试失败 |
+| webapp | 调度器的 Web UI |
+| website | 网站内容（不包括文档） |
影响版本字段可以设置为您发现错误的YuniKorn的最早版本。
如果您不确定，则将其留空。
+:::note
+如果您认为对于还不熟悉该项目的人来说这是一个好问题，您可以将 JIRA 的标签设置为 *newbie*。
+:::
+
如果您是打算修复该错误的开发人员，请将您的 JIRA ID 放在 Assignee 字段中。
请注意，您需要在 Apache YuniKorn 的贡献者列表中才能分配 JIRA ticket。
如果您还没有被添加到列表中，请发送电子邮件到
[[email protected]](mailto:[email protected]) 邮件列表或在 jira 的评论中请求它。
diff --git a/src/pages/community/how_to_contribute.md
b/src/pages/community/how_to_contribute.md
index 5d9f396..f40323e 100644
--- a/src/pages/community/how_to_contribute.md
+++ b/src/pages/community/how_to_contribute.md
@@ -27,7 +27,7 @@ under the License.
YuniKorn uses:
* JIRA for issue tracking.
* GitHub Pull Requests to manage code review and the change itself.
-* Markdown in the source tree for the documentation.
+* Markdown for documentation, versioned and stored in the website repository.
## Find an issue
We use JIRA issues to track bugs for this project.
@@ -51,7 +51,8 @@ If you cannot assign the JIRA to yourself ask the community
to help assign it an
## Fix an issue
Fixes or improvement must be created on the `master` branch.
Fork the relevant YuniKorn project into your own project and checkout the
`master` branch.
-Make sure that you have an up to date code revision checked out before you
start.
+If the same issue exist in an earlier release branch it can be back ported
after the fix has been added to master.
+Make sure that you have an up-to-date code revision checked out before you
start. Use `git status` to see if you are up-to-date.
Create a branch to work on, a good name to use is the JIRA ID you are working
on.
Now start coding! As you are writing your patch, please keep the following
things in mind:
@@ -66,23 +67,102 @@ In general, if you find a bug while working on a specific
feature, file a JIRA f
This helps us to differentiate between bug fixes and features and allows us to
build stable maintenance releases.
Make sure you have observed the recommendations in the [coding
guidelines](coding_guidelines).
-Before you commit you should also run the full test suite using `make test`.
-Make sure that all the tests pass.
+Before you commit your changes and create a pull request based on your changes
you should run the code checks.
+These same checks are run as part of the pull request workflow.
+The pull request workflow performs the following checks:
+* Apache license check: `make license-check`.
+* Go lint check: `make lint`.
+* Full unit test suite: `make test`.
+
+These three checks should pass locally before opening a pull request.
+As part of the pull request workflow all checks must pass before the change is
committed.
+For first time contributors to a repository the automated pull request
workflow must be approved by a committer.
+Once the workflow has run and has given a pass (a +1 vote) a committer will
review the patch.
+
+As part of the Kubernetes shim there is also a set of tests defined called the
_end to end_ tests.
+These tests are more complex to execute as they require some extra tools to be
installed.
+Execution, and a pass, of the tests is strongly recommended for changes to the
Kubernetes shim repository.
+They can be executed locally via `make e2e_test`.
Finally, please write a good, clear commit message, with a short, descriptive
title.
The descriptive title must start with the JIRA ID you are working on.
An example is: `[YUNIKORN-2] Support Gang Scheduling`
-The commit message will be used to pre-fill the pull request information.
-The JIRA ID in the message will automatically link the pull request and the
JIRA.
-The message that follows can be used to explain what the problem was, and how
it was fixed.
+The body of the commit message is used to describe the change made.
+The whole commit message will be used to pre-fill the pull request information.
+The body of the first commit message will be added to the PR Template.
+The JIRA ID in the message will automatically link the pull request and the
JIRA this is an essential part of tracking JIRA progress.
+
+## Changes that modify multiple repositories
+Apache YuniKorn consists of a number of repositories. Certain bug fixes or
features will require modification in 2 or more repositories.
+The dependencies are only relevant for the code repositories.
+
+| repository | depends on |
+|------------------------------|---------------------------------------------|
+| yunikorn-core | yunikorn-scheduler-interface |
+| yunikorn-k8shim | yunikorn-scheduler-interface, yunikorn-core |
+| yunikorn-scheduler-interface | none |
+| yunikorn-web | yunikorn-core |
+
+The dependency between the web UI and the core code is limited to the exposed
REST API.
+Not all REST API end points are used in the web UI. Manually testing the web
UI against the new REST API is required before approving and committing changes.
+As a general rule there is an impact on the web UI if a change in the REST API
removes or updates existing fields or completely removes existing end points.
+Additional end points or fields should not require a web UI update but still
require manual testing.
+
+The scheduler interface, core and K8shim have a dependency based on the [Go
modules](https://go.dev/blog/using-go-modules) that they import.
+
+We follow the version numbering as described in the [version
numbering](https://go.dev/doc/modules/version-numbers) for go modules.
+The master branch *must* use a pseudo version.
+See the [Go module dependencies](/docs/next/developer_guide/dependencies) for
updating the pseudo version.
+The release branches *must* use branch version.
+See the [release
procedure](release_procedure#tag-and-update-release-for-version) on when and
how to update the tags and references during the release creation.
+
+## Documentation updates
+Documentation is published and maintained as part of the website.
+The process for updating the documentation is the same as for making code
changes: file a jira and open a pull-request with the change.
+Multiple versions of the documentation are published on the website.
+Changes are always made against the `master` branch.
+The versioned documents and sidebars should only be updated to fix errors that
cannot wait for a release.
+
+Images that are part of a documentation page must be located in the `assets`
directory as part of the documents, i.e. `docs/assets`.
+All other images that are used, for instance the homepage and menu, that do
not change when or if the documentation is updated/versioned must be located in
the `static/img` directory.
+
+The versioned documentation and sidebar are located in:
+- versioned_docs: the released version of documentation
+- versioned_sidebars: the sidebars for the corresponding released documentation
+
+Normal documentation maintenance must be performed by updating the non
versioned documentation.
+New pages are added by:
+* adding a Markdown file
+* updating the `sidebar.js` file
+
+The page file must contain:
+* id and title definition (docusaurus syntax)
+* Apache license
+
+The id is used by docusaurus to link the page to the specific point in the
documentation menu.
+The title is displayed in the menu.
+```
+---
+id: MyPageID
+title: My new documentation page
+---
+```
+Pages can be grouped in categories in the sidebar.
+The category should be represented as directories in the source tree.
+
+After making the changes you can build the website locally in development mode
with the following command:
+```shell script
+./local-build.sh run
+```
+The only requirement is that you have docker installed as the build and server
will be run inside a docker container.
## Create a pull request
Please create a pull request on github with your patch.
See [opening a pull
request](https://help.github.com/articles/using-pull-requests/) for all the
details.
-For committers: You can create a new branch, push your change and create a PR
using the GitHub UI.
-For contributors: you have already forked the repository and committed your
changes to your fork.
+Recommendation is to use a fork of the repository and create a branch in your
fork.
Use the GitHub UI to create a PR using the `compare across forks` option.
+In most cases the GitHub UI, after a short delay, will provide you the option
to create a PR when a commit is detected on a forked repository.
The pull request description must include the JIRA reference that you are
working on.
If you set the commit message as described above the pull request will
automatically pick it up.
@@ -91,20 +171,58 @@ For example a pull request linked to
[YUNIKORN-2](https://issues.apache.org/jira
`[YUNIKORN-2] Support Gang Scheduling`
## Committing a change
-When a change is approved it will be committed to the `master` branch of the
repository.
-The commit message must include the JIRA in the first line and should include
a `Closes #1` as a
-A commit will automatically close the PR.
-The JIRA will not be closed automatically.
-
-## Report a security issue
-YuniKorn community cares deeply about the security and actively addresses any
security issues as
-the top priority. We follow the Apache security guidelines for handling
security issues, please see the Apache doc
-about [handling security issues](https://www.apache.org/security/). If you
find any security issue,
-please send a vulnerability report to [email protected], the YuniKorn
security team will assess the issue
-immediately and work with the reporter on a plan to fix it. Please do not
disclose the issue to any public forum
-before working with the security team.
+When a change is approved a committer will commit the change to the `master`
branch of the repository.
+Commits follow the "squash and merge" approach. This squashes all commits for
a pull request into one commit which is then merged.
+
+After committing a change the JIRA associated with the pull request will not
be automatically closed.
+The JIRA status should be resolved manually and the correct `Fixed Version/s`
should be set when resolving.
+If a patch is back ported into a branch the JIRA should show multiple `Fixed
Version/s`.
+One for the upcoming version for the master and one for each branch the fix is
ported back to.
+
+There are three options for committing a change:
+* use the script (recommended)
+* manually using the git command line
+* use the GitHub web UI "squash and merge" button
+
+A [simple shell
script](https://github.com/apache/yunikorn-release/tree/master/tools/merge-pr.sh)
to help with a squash and merge is part of the release repository.
+The script handles the checkout, merge and commit message preparation.
+As part of the merge process conflicts can be resolved by the committer and
added to the commit.
+The commit message is prepared but not finalised. The committer can edit, and
cleanup, the message before the commit is made.
+Changes are pushed as the last step of the process.
+Abandoning the process leaves the local system in the same state as it was
before the commit process started.
+
+:::caution
+Using the GitHub web UI there is no control over the author or committers
details.
+
+The committer is always set to "GitHub <[email protected]>".
+The user logged into the GitHub web UI and performing the action is not
tracked in the commit.
+The author name is influenced by the GitHub setting "Keep my email addresses
private",
+this can cause author names like "username
<[email protected]>" to be used.
+:::
+
+Commit messages **must** comply to a simple set of rules:
+* Subject line is the title of the change formatted as follows: `[JIRA
reference] subject (#PR ID)`.
+* Second line must be empty, separates the subject from the body.
+* The body of the message contains the description of the change.
+* All lines in the commit message should be wrapped at 72 characters.
+
+For all commits, via the command line or the GitHub web UI, the message body
must be reviewed.
+During the pull request review process multiple commits could be added and
some text that end up in the commit message might be irrelevant.
+Text like `review comment changes` or `fixed unit test` do not need to be part
of the final commit message.
+
+The pull request will automatically be marked as `merged` when the GitHub UI
is used.
+To close the pull request when using the git command line one of the magic
phrases can be used in a commit message.
+Including one of these "magic words" followed by the pull request ID in the
commit summary will automatically close the pull request.
+The script will automatically add the `Closes: #PR` phrase to the commit
message.
+For more information check this [GitHub help
page](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
for more magic phrases.
+
+An example of a pull request committed using the script see PR #329 for the
YuniKorn core: [PR 329
commit](https://github.com/apache/yunikorn-core/commit/9e151829e14714b0e47b413bd9cecfdff6b44507)
## Still got questions?
If you’re not sure about something, try to follow the style of the existing
codebase.
Look at whether there are other examples in the code that do a similar thing.
Feel free to ask questions on the
[[email protected]](mailto:[email protected]) list as well.
+
+See Also
+* [Apache contributor
documentation](http://www.apache.org/dev/contributors.html)
+* [Apache voting documentation](http://www.apache.org/foundation/voting.html)
diff --git a/src/pages/community/reporting_issues.md
b/src/pages/community/reporting_issues.md
index e6cbdfc..4c43a2f 100644
--- a/src/pages/community/reporting_issues.md
+++ b/src/pages/community/reporting_issues.md
@@ -22,25 +22,29 @@ specific language governing permissions and limitations
under the License.
-->
-# Reporting Issues
-
-## For YuniKorn Users
+## Reporting a security issue
+YuniKorn community cares deeply about the security and actively addresses any
security issues as
+the top priority. We follow the Apache security guidelines for handling
security issues, please see the Apache doc
+about [handling security issues](https://www.apache.org/security/). If you
find any security issue,
+please send a vulnerability report to
[[email protected]](mailto:[email protected]), the YuniKorn security team
will assess the issue
+immediately and work with the reporter on a plan to fix it.
+Please do not disclose the issue to any public forum before working with the
security team.
+
+## Non security issues
If you have an issue with YuniKorn operation, please follow these guidelines:
If you are having an issue with setup, configuration, or some other form of
behavior not matching your expectation, join the user mailing list and ask your
questions in that forum.
-See the [YuniKorn web page](https://yunikorn.apache.org) for information on
mailing lists.
-You can also ask the YuniKorn slack channel for help, check the web page for
details on how to join.
+See the [Get Involved](get_involved#communication-channels) page for
information on mailing lists.
+You can also ask the YuniKorn slack channel for help, details on how to join
can be found on the same page.
If you have a bug that needs a fix in the code or in the documentation, please
follow the procedure in [Filing a JIRA](#filing-a-jira-for-yunikorn-issues)
below.
-## For YuniKorn Developers
JIRA is used by the Apache YuniKorn project to track all issues.
These include:
1. Add new features
1. Improving existing features
1. Report bugs that need to be fixed in the codebase
-If you are interested in tracking development issues in JIRA, you can browse
-this [link](https://issues.apache.org/jira/projects/YUNIKORN).
+If you are interested in tracking development issues in JIRA, you can browse
this [link](https://issues.apache.org/jira/projects/YUNIKORN).
## Filing a JIRA for YuniKorn issues
Go to the Apache JIRA page to file your issue.
@@ -57,27 +61,33 @@ For Summary, please provide a detailed title e.g. _K8 pod
not scheduled in an em
Please set the component field if you have isolated the issue to a particular
component:
-| Component | Description |
-|-----------|-------------|
-| build| Project build, build scripts, and git issues|
-| core - cache | Core scheduler cache |
-| core - common | Common code, like resources, for the core scheduler|
-| core - scheduler | Core scheduling issues |
-| documentation | Documentation fixes and enhancements |
-| scheduler-interface | Scheduler interface specification |
-| security | Security related issues |
-| shim - kubernetes | K8shim issues |
-| shim - yarn | Hadoop YARN shim issues |
-| test - smoke | Smoke test failures |
-| test - unit | Unit test failures |
-| webapp | Web UI for the scheduler |
+| Component | Description |
+|---------------------|-----------------------------------------------------|
+| build | Project build, build scripts, and git issues |
+| core - common | Common code, like resources, for the core scheduler |
+| core - scheduler | Core scheduling issues |
+| documentation | Documentation fixes and enhancements |
+| scheduler-interface | Scheduler interface specification |
+| security | Security related issues (encryption, authz & authn) |
+| shim - kubernetes | K8shim issues |
+| shim - yarn | Hadoop YARN shim issues |
+| test - smoke | Smoke test failures |
+| test - unit | Unit test failures |
+| webapp | Web UI for the scheduler |
+| website | Website content (does not include documentation) |
The Affects Versions/s field can be set to the earliest version of YuniKorn
where you have seen the bug.
If you are not sure then just leave it empty.
+Additionally, do not set the Fix Version. Committers use this field to
determine which branches have had patches committed.
+Instead, use the Affects and Target Versions to notify others of the branches
that should be considered.
+
+:::note
+You can set the label for a JIRA to *newbie* if you think that it is a good
issue for someone who is not familiar with the project yet.
+:::
If you are a developer intending to fix the bug, put your JIRA ID in the
Assignee field.
Note that you need to be in the contributors list of Apache YuniKorn in order
to be able to be assign a JIRA ticket.
-If you have not been added to the list, send an email to the
[[email protected]](mailto:[email protected]) mailing list or ask
in a comment of the jira to request for it.
+If you have not been added to the list, email the
[[email protected]](mailto:[email protected]) mailing list or ask
in a comment of the jira to request for it.
Please put as much detail as possible in the Description field.
Include your configuration changes, cluster size, and YuniKorn version.
@@ -90,4 +100,4 @@ If you have already tried to debug the issue describe the
steps you have already
Even if that result was that you were not able to reproduce the issue.
For new feature requests, it may include a design document.
-If you do not have that or it is just a generic request work with us to design
your feature and implement it.
+If you do not have that, or it is just a generic request, work with us to
design your feature and implement it.
