This is an automated email from the ASF dual-hosted git repository.
juripetersen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/wayang-website.git
The following commit(s) were added to refs/heads/main by this push:
new 272ad9cc Community docs fixes (#135)
272ad9cc is described below
commit 272ad9ccc7db3f1624748725f09dbb0db4fdc16f
Author: Zoi Kaoudi <[email protected]>
AuthorDate: Wed Nov 4 17:42:15 2026 +0100
Community docs fixes (#135)
* docs: point issue reporting to GitHub issues instead of Jira
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
* docs: use post-graduation repository URLs on Repositories page
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
* docs: update contribution and committer guides, reorder community sidebar
- How to contribute: replace Jira with GitHub issues throughout, remove
leftover Spark references and non-existent user@ list, use main branch
and post-graduation repository URLs, link the AI tooling policy.
- Becoming a committer: (P)PMC -> PMC, remove Spark leftovers, fix typos.
- Sidebar: move Maturity Model right before Wayang Security.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
* docs: remove Community Resources page, move Blog into community sidebar
The Community navbar item becomes a direct link to the community docs,
since the dropdown would otherwise only contain one entry.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
* docs: restructure Repositories page
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
* docs: list How to contribute before Becoming a committer
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
* docs: review fixes and non-code contributions in How to contribute
- Add a 'Contributing by spreading the word' section (talks, blog posts,
social media, teaching, use cases).
- Fix factual errors: Java style is Google Java Style (Checkstyle with
google_checks.xml), not Oracle; drop the inherited Python line-length
exception; resolve the contradiction about ML algorithms vs ML4ALL.
- Fix the broken list/code block in the pull request steps, add the
build command, note force-push after rebase, remove a duplicated
licence statement, soften gatekeeping wording, fix heading levels.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
* docs: emphasise engagement and non-code merit on committer page
- Committership is about commitment and sustained engagement, not only
code; list the kinds of contributions the PMC considers.
- Add what is expected of a committer, and separate the PMC section.
- Clarify review policy on both committer and contribution pages: one
committer approval for small changes, two recommended for larger ones.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
* docs: remove 'Contributing user libraries' section inherited from Spark
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
* docs: place Blog link after Repositories in community sidebar
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_015EbsXcrjsNeGmb5zxooUan
---------
Co-authored-by: Claude Opus 5.5 <[email protected]>
---
docs/community/ai-tooling-policy.md | 4 +
docs/community/committer.md | 61 ++++++---
docs/community/contribute.md | 243 +++++++++++++++---------------------
docs/community/maturity.md | 2 +-
docs/community/repositories.md | 24 ++--
docs/community/resources.md | 23 ----
docs/community/security.md | 4 +
docusaurus.config.ts | 33 +++--
sidebars.ts | 2 +
9 files changed, 187 insertions(+), 209 deletions(-)
diff --git a/docs/community/ai-tooling-policy.md
b/docs/community/ai-tooling-policy.md
index 24938426..3cd7a26e 100644
--- a/docs/community/ai-tooling-policy.md
+++ b/docs/community/ai-tooling-policy.md
@@ -1,3 +1,7 @@
+---
+sidebar_position: 9
+---
+
# Guidelines for AI-assisted Contributions
The Apache Wayang community welcomes the use of AI and generative tooling as
part of the contribution process, provided contributors follow the guidelines
below. These guidelines align with the [ASF Generative Tooling
Guidance](https://www.apache.org/legal/generative-tooling.html).
diff --git a/docs/community/committer.md b/docs/community/committer.md
index d14b22c1..ca3476e3 100644
--- a/docs/community/committer.md
+++ b/docs/community/committer.md
@@ -5,40 +5,64 @@ id: committer
---
-To get started contributing to Wayang, learn how to contribute – anyone can
submit patches, documentation and examples to the project.
+Being a committer is about **commitment to the project**, not only about
committing code. Committers are people who care about Wayang, are engaged with
its community, and stay active over time. Write access to the repositories
comes with that role, but it is not what defines it.
-The (P)PMC regularly adds new committers from the active contributors, based
on their contributions to Wayang. The qualifications for new committers include:
+Anyone can contribute: see [How to contribute](/docs/community/contribute) for
the many ways to get started. The PMC regularly invites new committers from the
active contributors.
-### Sustained contributions to Wayang:
-Committers should have a history of major contributions to Wayang. An ideal
committer will have contributed broadly throughout the project, and have
contributed at least one major component where they have taken an “ownership”
role. An ownership role means that existing contributors feel that they should
run patches for this component by this person.
+## What we look for
-__Quality of contributions__: Committers more than any other community member
should submit simple, well-tested, and well-designed patches. In addition, they
should show sufficient expertise to be able to review patches, including making
sure they fit within Wayang's engineering practices (testability,
documentation, API stability, code style, etc). The committership is
collectively responsible for the software quality and maintainability of Spark.
Note that contributions to critical par [...]
+__Commitment and engagement__: The most important quality is sustained, active
involvement. Committers follow the dev@ mailing list, take part in discussions
and votes, respond to questions and pull requests, and keep showing up over
months, not just for a single contribution. Steady engagement counts for more
than one large contribution followed by silence.
-__Community involvement__: Committers should have a constructive and friendly
attitude in all community interactions. They should also be active on the dev
and user list and help mentor newer contributors and users. In design
discussions, committers should maintain a professional and diplomatic approach,
even in the face of disagreement.
-The type and level of contributions considered may vary by project area – for
example, we greatly encourage contributors who want to work on mainly the
documentation, or mainly on platform support for specific OSes, storage
systems, etc.
+__Contributions of any kind__: Contributions do not have to be code. Following
the [ASF’s view of merit](https://community.apache.org/contributors/), the PMC
considers everything that helps the project, for example:
-The (P)PMC also adds new (P)PMC members. (P)PMC members are expected to carry
out (P)PMC responsibilities as described in [Apache
Guidance](https://www.apache.org/dev/pmc.html#policy), including helping vote
on releases, enforce Apache project trademarks, take responsibility for legal
and license issues, and ensure the project follows Apache project mechanics.
The PMC periodically adds committers to the PMC who have shown they understand
and can help with these activities.
+- code, tests, and reviews of other people’s pull requests
+- documentation, tutorials, examples, and the website
+- testing release candidates and reporting bugs
+- answering questions on the mailing list and in issues
+- giving talks, writing blog posts, and promoting Wayang on social media
+- mentoring students and newcomers, and organizing events
-### Review process
-All contributions should be reviewed before merging as described in
Contributing to Wayang. In particular, if you are working on an area of the
codebase you are unfamiliar with, look at the Git history for that code to see
who reviewed patches before. You can do this using git log `--format=full
<filename>`, by examining the “Commit” field to see who committed each patch.
+An ideal committer has taken an “ownership” role in some area, whether that is
a component of the codebase, the documentation, the release process, or
community outreach, so that others naturally turn to them for that area.
+
+__Quality and care__: Whatever you contribute, do it carefully. For code, this
means simple, well-tested, and well-designed changes that fit Wayang’s
engineering practices (testability, documentation, API stability, code style).
Committers who work on code should also be able to review others’ changes;
contributions to critical parts of Wayang, like its core and optimizer, are
held to a higher standard.
+
+__Community involvement__: Committers have a constructive and friendly
attitude in all community interactions. They help and mentor newer contributors
and users, and in design discussions they maintain a professional and
diplomatic approach, even in the face of disagreement.
+
+## What is expected of a committer
+
+Becoming a committer is a recognition of what you have already done, and an
invitation to keep doing it. Committers are expected to:
+
+- stay engaged with the project and the dev@ mailing list
+- help review pull requests and answer questions in their areas
+- welcome and guide new contributors
+- take part in project discussions and decisions, and use their write access
responsibly (see below)
+
+If your circumstances change and you can no longer be active, that is fine:
let the PMC know at
[[email protected]](mailto:[email protected]). You remain a
committer, and you are always welcome back.
+
+## Becoming a PMC member
+
+The PMC also adds new PMC members. PMC members are expected to carry out PMC
responsibilities as described in [Apache
Guidance](https://www.apache.org/dev/pmc.html#policy), including helping vote
on releases, enforce Apache project trademarks, take responsibility for legal
and license issues, and ensure the project follows Apache project mechanics.
The PMC periodically adds committers to the PMC who have shown they understand
and can help with these activities.
+
+## Review process
+All contributions should be reviewed before merging as described in [How to
contribute](/docs/community/contribute). In particular, if you are working on
an area of the codebase you are unfamiliar with, look at the Git history for
that code to see who reviewed patches before. You can do this using `git log
--format=full <filename>`, by examining the “Commit” field to see who committed
each patch.
## When to commit/merge a pull request
PRs shall not be merged during active, on-topic discussion unless they address
issues such as critical security fixes of a public vulnerability. Under
extenuating circumstances, PRs may be merged during active, off-topic
discussion and the discussion directed to a more appropriate venue. Time should
be given prior to merging for those involved with the conversation to explain
if they believe they are on-topic.
Lazy consensus requires giving time for discussion to settle while
understanding that people may not be working on Wayang as their full-time job
and may take holidays. It is believed that by doing this, we can limit how
often people feel the need to exercise their veto.
-All -1s with justification merit discussion. A -1 from a non-committer can be
overridden only with input from multiple committers, and suitable time must be
offered for any committer to raise concerns. A -1 from a committer who cannot
be reached requires a consensus vote of the (P)PMC under ASF voting rules to
determine the next steps within the ASF guidelines for code vetoes. The Wayang
project typically uses a 72h time window to conclude votes.
+All -1s with justification merit discussion. A -1 from a non-committer can be
overridden only with input from multiple committers, and suitable time must be
offered for any committer to raise concerns. A -1 from a committer who cannot
be reached requires a consensus vote of the PMC under ASF voting rules to
determine the next steps within the ASF guidelines for code vetoes. The Wayang
project typically uses a 72h time window to conclude votes.
These policies serve to reiterate the core principle that code must not be
merged with a pending veto or before a consensus has been reached (lazy or
otherwise).
-It is the (P)PMC’s hope that vetoes continue to be infrequent, and when they
occur, that all parties will take the time to build consensus prior to
additional feature work.
+It is the PMC’s hope that vetoes continue to be infrequent, and when they
occur, that all parties will take the time to build consensus prior to
additional feature work.
Being a committer means exercising your judgement while working in a community
of people with diverse views. There is nothing wrong in getting a second (or
third or fourth) opinion when you are uncertain. Thank you for your dedication
to the Wayang project; it is appreciated by the developers and users of Wayang.
It is hoped that these guidelines do not slow down development; rather, by
removing some of the uncertainty, the goal is to make it easier for us to reach
consensus. If you have ideas on how to improve these guidelines or other Wayang
project operating procedures, you should reach out on the dev@ list to start
the discussion.
## How we merge a pull request
-Changes pushed to the master branch on Apache cannot be removed; that is, we
can’t force-push to it. So please don’t add any test commits or anything like
that, only real patches. We typically enforce a review from minimum two
committers, who are ideally owners of submodules, like ML4ALL or JDBC. They
investigate the PR, add remarks and request changes. Please be not insultet in
any way, the team needs to make sure that all code committed to `main` has a
igh quality and does not break cu [...]
+Changes pushed to the `main` branch on Apache cannot be removed; that is, we
can’t force-push to it. So please don’t add any test commits or anything like
that, only real patches. Every pull request needs at least one approving review
from a committer before it can be merged. For small changes, such as bug fixes,
typos, or documentation updates, one approval is enough. For larger changes,
such as new features, API changes, or changes to the optimizer or core, we
recommend reviews from tw [...]
### Policy on backporting bug fixes
We go in line with pwendell (Apache Spark PMC):
@@ -54,11 +78,12 @@ I think the following facets are important to consider:
1. Both the bug and the fix are well understood and isolated. Code being
modified is well tested.
2. The bug being addressed is high priority to the community.
-3. The backported fix does not vary widely from the master branch fix.
-4. We tend to avoid backports in the converse situations:
+3. The backported fix does not vary widely from the `main` branch fix.
+
+We tend to avoid backports in the converse situations:
-The bug or fix are not well understood. For instance, it relates to
interactions between complex components or third party libraries (e.g. Hadoop
libraries). The code is not well tested outside of the immediate bug being
fixed.
-The bug is not clearly a high priority for the community.
-The backported fix is widely different from the master branch fix.
+- The bug or fix are not well understood. For instance, it relates to
interactions between complex components or third party libraries (e.g. Hadoop
libraries). The code is not well tested outside of the immediate bug being
fixed.
+- The bug is not clearly a high priority for the community.
+- The backported fix is widely different from the `main` branch fix.
diff --git a/docs/community/contribute.md b/docs/community/contribute.md
index 01281bf4..1fb74dad 100644
--- a/docs/community/contribute.md
+++ b/docs/community/contribute.md
@@ -1,92 +1,81 @@
---
title: How to contribute
-sidebar_position: 5
+sidebar_position: 4
id: contribute
---
This guide documents the best way to make various types of contribution to
Apache Wayang, including what is required before submitting a code change.
-Contributing to Wayang doesn’t just mean writing code. Helping new users on
the mailing list, testing releases, and improving documentation are also
welcome. In fact, proposing significant code changes usually requires first
gaining experience and credibility within the community by helping in other
ways. This is also a guide to becoming an effective contributor.
+Contributing to Wayang doesn’t just mean writing code. Helping new users on
the mailing list, testing releases, improving documentation, giving talks, and
spreading the word on social media are all valuable contributions. For larger
code changes, it helps to first get to know the community and the codebase, for
example through some of the contributions below, so that your proposal fits
where the project is heading.
-So, this guide organizes contributions in order that they should probably be
considered by new contributors who intend to get involved long-term. Build some
track record of helping others, rather than just open pull requests.
+The guide starts with ways to contribute that don’t require code and ends with
the process for code changes.
-### Contributing by helping other users
-A great way to contribute to Wayang is to help answer user questions on the
user@ mailing list or on StackOverflow. There are always many new Wayang users;
taking a few minutes to help answer a question is a very valuable community
service.
+## Contributing by helping other users
+A great way to contribute to Wayang is to help answer user questions on the
dev@ mailing list or in [GitHub
issues](https://github.com/apache/wayang/issues). There are always new Wayang
users; taking a few minutes to help answer a question is a very valuable
community service.
-Contributors should subscribe to this list and follow it in order to keep up
to date on what’s happening in Wayang. Answering questions is an excellent and
visible way to help the community, which also demonstrates your expertise.
+Contributors should subscribe to the dev@ list and follow it in order to keep
up to date on what’s happening in Wayang. Answering questions is an excellent
and visible way to help the community, which also demonstrates your expertise.
-See the [Mailing Lists](/docs/community/mailinglist) guide for guidelines
about how to effectively participate in discussions on the mailing list, as
well as forums like StackOverflow.
+See the [Mailing Lists](/docs/community/mailinglist) guide for guidelines
about how to effectively participate in discussions on the mailing list.
-### Contributing by testing releases
-Wayang’s release process is community-oriented, and members of the community
can vote on new releases on the dev@ mailing list. Wayang users are invited to
subscribe to this list to receive announcements, and test their workloads on
newer release and provide feedback on any performance or correctness issues
found in the newer release.
+## Contributing by testing releases
+Wayang’s release process is community-oriented, and members of the community
can vote on new releases on the dev@ mailing list. Wayang users are invited to
subscribe to this list to receive announcements, test their workloads on newer
releases, and provide feedback on any performance or correctness issues found.
## Contributing by reviewing changes
-Changes to Wayang source code are proposed, reviewed and committed via GitHub
pull requests (described later). Anyone can view and comment on active changes
here. Reviewing others’ changes is a good way to learn how the change process
works and gain exposure to activity in various parts of the code. You can help
by reviewing the changes and asking questions or pointing out issues – as
simple as typos or small issues of style.
+Changes to Wayang source code are proposed, reviewed and committed via [GitHub
pull requests](https://github.com/apache/wayang/pulls) (described later).
Anyone can view and comment on active changes there. Reviewing others’ changes
is a good way to learn how the change process works and gain exposure to
activity in various parts of the code. You can help by reviewing the changes
and asking questions or pointing out issues – as simple as typos or small
issues of style.
## Contributing documentation changes
-To propose a change to release documentation (that is, docs that appear under
[Developer](/docs/guide/getting-started) section), fork the website repo and
edit the Markdown source files in Wayang’s docs/ directory, the README file
shows how to build the documentation locally to test your changes. The process
to propose a doc change is otherwise the same as the process for proposing code
changes below.
+The documentation on this website, including the
[Developer](/docs/guide/getting-started) guides, lives in the
[wayang-website](https://github.com/apache/wayang-website) repository. To
propose a change, fork that repository, edit the Markdown files under `docs/`
(or `blog/` for blog posts), and open a pull request. The repository's README
shows how to build the site locally to check your changes.
-To propose a change to the rest of the documentation (that is, docs that do
__not__ appear under [Developer](/docs/guide/getting-started) section),
similarly, edit the Markdown in the wayang-website repository and open a pull
request.
+Javadoc and other documentation generated from the source code are changed in
the [main Wayang repository](https://github.com/apache/wayang), following the
same process as code changes below.
-## Contributing user libraries to Wayang
-Just as Java and Scala applications can access a huge selection of libraries
and utilities, none of which are part of Java or Scala themselves, Wayang aims
to support a rich ecosystem of libraries. Many new useful utilities or features
belong outside of Spark rather than in the core. For example: query optimizer
code and language support probably has to be a part of core Wayang, but, useful
machine learning algorithms can happily exist outside of Wayang.
+## Contributing by spreading the word
+You don’t need to write code to make a real difference. Helping more people
discover and understand Wayang is one of the most valuable contributions, and
the PMC takes it into account when considering new committers. For example:
-To that end, large and independent new functionality is often rejected for
inclusion in Wayang itself, but, can and should be hosted as a separate project
and repository, and included in the wayang-packages.org collection.
+- **Give a talk** about Wayang at a meetup, conference, lecture, or company
tech talk. Let us know on dev@ so we can help spread the word.
+- **Write a blog post or tutorial** about how you use Wayang, a benchmark you
ran, or a lesson learned. We are happy to publish posts on the [Wayang
blog](/blog): open a pull request in the
[wayang-website](https://github.com/apache/wayang-website) repository with your
post under `blog/`, or link to it from your own site.
+- **Share on social media**: post about releases, blog posts, and your own
Wayang experiments, and follow the project on
[LinkedIn](https://www.linkedin.com/company/apachewayang),
[X](https://twitter.com/apachewayang), and
[YouTube](https://www.youtube.com/@apachewayang).
+- **Teach with Wayang**: use it in a course, supervise a student project or
thesis, or mentor in programmes like Google Summer of Code.
+- **Tell us about your use case**: knowing who uses Wayang and how helps the
project set priorities and shows others what is possible. Share it on dev@.
## Contributing bug reports
-Ideally, bug reports are accompanied by a proposed code change to fix the bug.
This isn’t always possible, as those who discover a bug may not have the
experience to fix it. A bug may be reported by creating a
[JIRA](https://issues.apache.org/jira/projects/WAYANG/issues/WAYANG-16?filter=allopenissues)
or a [GitHub Issue](https://github.com/apache/incubator-wayang/issues) but
without creating a pull request (see below).
+Ideally, bug reports are accompanied by a proposed code change to fix the bug.
This isn’t always possible, as those who discover a bug may not have the
experience to fix it. A bug may be reported by opening a [GitHub
issue](https://github.com/apache/wayang/issues/new) without creating a pull
request (see below).
-Bug reports are only useful however if they include enough information to
understand, isolate and ideally reproduce the bug. Simply encountering an error
does not mean a bug should be reported; as below, search JIRA and search and
inquire on the Wayang user / dev mailing lists first. Unreproducible bugs, or
simple error reports, may be closed.
+Bug reports are only useful, however, if they include enough information to
understand, isolate and ideally reproduce the bug. Simply encountering an error
does not mean a bug should be reported; as below, search the existing GitHub
issues and the dev@ mailing list archives first. Unreproducible bugs, or simple
error reports, may be closed.
-It’s very helpful if the bug report has a description about how the bug was
introduced, by which commit, so that reviewers can easily understand the bug.
It also helps committers to decide how far the bug fix should be backported,
when the pull request is merged. The pull request to fix the bug should narrow
down the problem to the root cause.
+If you know how the bug was introduced, for example by which commit, mention
it so that reviewers can easily understand it. The pull request to fix the bug
should narrow down the problem to the root cause.
Performance regression is also one kind of bug. The pull request to fix a
performance regression must provide a benchmark to prove the problem is indeed
fixed.
-Note that, data correctness/data loss bugs are very serious. Make sure the
corresponding bug report JIRA ticket is labeled as correctness or data-loss. If
the bug report doesn’t get enough attention, please send an email to dev@, to
draw more attentions.
+Note that data correctness and data loss bugs are very serious. Make this
clear in the issue title and description. If the bug report doesn’t get enough
attention, please send an email to dev@ to draw more attention to it.
-It is possible to propose new features as well. These are generally not
helpful unless accompanied by detail, such as a design document and/or code
change. Large new contributions should consider wayang-packages.org first (see
above), or be discussed on the mailing list first. Feature requests may be
rejected, or closed after a long period of inactivity.
+It is possible to propose new features as well. These are generally not
helpful unless accompanied by detail, such as a design document and/or code
change. Large new contributions should be discussed on the mailing list first.
Feature requests may be rejected, or closed after a long period of inactivity.
-### Contributing to JIRA maintenance
-Given the volume of issues raised in the Apache Wayang JIRA, inevitably some
issues are duplicates, or become obsolete and eventually fixed otherwise, or
can’t be reproduced, or could benefit from more detail, and so on. It’s useful
to help identify these issues and resolve them, either by advancing the
discussion or even resolving the JIRA. Most contributors are able to directly
resolve JIRAs. Use judgment in determining whether you are quite confident the
issue should be resolved, alth [...]
+## Contributing to issue triage
+Inevitably, some GitHub issues are duplicates, become obsolete, are fixed by
another change, can’t be reproduced, or could benefit from more detail. It’s
useful to help identify these issues, for example by adding a comment that
links to a duplicate, asking for a reproduction, or confirming that a bug still
exists on the latest `main`. Committers can then close or label the issue
accordingly.
-When resolving JIRAs, observe a few useful conventions:
-
-- Resolve as Fixed if there’s a change you can point to that resolved the issue
- - Set Fix Version(s), if and only if the resolution is Fixed
- - Set Assignee to the person who most contributed to the resolution, which
is usually the person who opened the PR that resolved the issue.
- - In case several people contributed, prefer to assign to the more
‘junior’, non-committer contributor
-
-- For issues that can’t be reproduced against master as reported, resolve as
Cannot Reproduce
- - Fixed is reasonable too, if it’s clear what other previous pull request
resolved it. Link to it.
- - If the issue is the same as or a subset of another issue, resolved as
Duplicate
- - Make sure to link to the JIRA it duplicates
- - Prefer to resolve the issue that has less activity or discussion as the
duplicate
-
-- If the issue seems clearly obsolete and applies to issues or components that
have changed radically since it was opened, resolve as Not a Problem
-- If the issue doesn’t make sense – not actionable, for example, a non-Spark
issue, resolve as Invalid
-- If it’s a coherent issue, but there is a clear indication that there is not
support or interest in acting on it, then resolve as Won’t Fix
-
-Sometimes, a contributor will already have a particular new change or bug in
mind. If seeking ideas, consult the list of starter tasks in JIRA, or ask the
user@ mailing list.
+## Preparing a code change
+Sometimes, a contributor will already have a particular new change or bug in
mind. If seeking ideas, browse the [open
issues](https://github.com/apache/wayang/issues) or ask on the dev@ mailing
list.
Before proceeding, contributors should evaluate if the proposed change is
likely to be relevant, new and actionable:
-1. Is it clear that code must change? Proposing a JIRA and pull request is
appropriate only when a clear problem or change has been identified. If simply
having trouble using Spark, use the mailing lists first, rather than consider
filing a JIRA or proposing a change. When in doubt, email user@ first about the
possible change
-2. Search the user@ and dev@ mailing list archives for related discussions.
Often, the problem has been discussed before, with a resolution that doesn’t
require a code change, or recording what kinds of changes will not be accepted
as a resolution.
-3. Search JIRA for existing issues:
https://issues.apache.org/jira/browse/WAYANG
-4. Is the scope of the change matched to the contributor’s level of
experience? Anyone is qualified to suggest a typo fix, but refactoring core
scheduling logic requires much more understanding of Wayang. Some changes
require building up experience first (see above).
-5. It’s worth reemphasizing that changes to the core of Wayang, or to highly
complex and important modules like SQL and Catalyst, are more difficult to make
correctly. They will be subjected to more scrutiny, and held to a higher
standard of review than changes to less critical code.
+1. Is it clear that code must change? Opening an issue and pull request is
appropriate only when a clear problem or change has been identified. If you are
simply having trouble using Wayang, use the mailing list first rather than
filing an issue or proposing a change. When in doubt, email dev@ first about
the possible change.
+2. Search the dev@ mailing list archives for related discussions. Often, the
problem has been discussed before, with a resolution that doesn’t require a
code change, or recording what kinds of changes will not be accepted as a
resolution.
+3. Search the [GitHub
issues](https://github.com/apache/wayang/issues?q=is%3Aissue) (open and closed)
and [pull requests](https://github.com/apache/wayang/pulls?q=is%3Apr) for
existing work.
+4. Is the scope of the change matched to the contributor’s level of
experience? Anyone is qualified to suggest a typo fix, but refactoring the
optimizer requires much more understanding of Wayang. Some changes require
building up experience first (see above).
+5. It’s worth reemphasizing that changes to the core of Wayang, or to highly
complex and important modules like the optimizer and the platform integrations,
are more difficult to make correctly. They will be subjected to more scrutiny,
and held to a higher standard of review than changes to less critical code.
-### ML4ALL and optimizer-specific contribution guidelines
-While a rich set of algorithms is an important goal for Wayang, scaling the
project requires that maintainability, consistency, and code quality come
first. New algorithms should:
+## Contributing new algorithms
+This applies, for example, to machine learning algorithms in ML4ALL. While a
rich set of algorithms is an important goal for Wayang, scaling the project
requires that maintainability, consistency, and code quality come first. New
algorithms should:
1. Be used and accepted (academic citations and concrete use cases can help
justify this)
2. Be well documented
3. Have APIs consistent with other algorithms in Wayang
4. Come with a reasonable expectation of developer support
-5. Error message guidelines
-6. Exceptions thrown in Wayang should be associated with standardized and
actionable error messages
-#### Error messages should answer the following questions:
+## Error message guidelines
+Exceptions thrown in Wayang should be associated with standardized and
actionable error messages.
+
+### Error messages should answer the following questions
- What was the problem?
- Why did the problem happen?
@@ -101,12 +90,11 @@ __When writing error messages, you should__:
5. Avoid sounding accusatory, judgmental, or insulting
6. Be direct
7. Do not use programming jargon in user-facing errors
-8 See the error message guidelines for more details.
-### Code review criteria
-Before considering how to contribute code, it’s useful to understand how code
is reviewed, and why changes may be rejected. See the detailed guide for code
reviewers from Google’s Engineering Practices documentation. Simply put,
changes that have many or large positives, and few negative effects or risks,
are much more likely to be merged, and merged quickly. Risky and less valuable
changes are very unlikely to be merged, and may be rejected outright rather
than receive iterations of review.
+## Code review criteria
+Before considering how to contribute code, it’s useful to understand how code
is reviewed, and why changes may be rejected. See the [guide for code
reviewers](https://google.github.io/eng-practices/review/) from Google’s
Engineering Practices documentation. Simply put, changes that have many or
large positives, and few negative effects or risks, are much more likely to be
merged, and merged quickly. Risky and less valuable changes are very unlikely
to be merged, and may be rejected outri [...]
-#### Positives
+### Positives
- Fixes the root cause of a bug in existing functionality
- Adds functionality or fixes a problem needed by a large number of users
- Simple, targeted
@@ -115,125 +103,102 @@ Before considering how to contribute code, it’s useful
to understand how code
- Reduces complexity and lines of code
- Change has already been discussed and is known to committers
-#### Negatives, risks
+### Negatives and risks
- Band-aids a symptom of a bug only
- Introduces complex new functionality, especially an API that needs to be
supported
- Adds complexity that only helps a niche use case
-- Adds user-space functionality that does not need to be maintained in Wayang,
but could be hosted externally and indexed by wayang-packages.org
+- Adds user-space functionality that does not need to be maintained in Wayang,
but could be hosted externally
- Changes a public API or semantics (rarely allowed)
- Adds large dependencies
- Changes versions of existing dependencies
- Adds a large amount of code
- Makes lots of modifications in one “big bang” change
-### Contributing code changes
+## Contributing code changes
Please review the preceding section before proposing a code change. This
section documents how to do so.
__When you contribute code, you affirm that the contribution is your original
work and that you license the work to the project under the project’s open
source license. Whether or not you state this explicitly, by submitting any
copyrighted material via pull request, email, or other means you agree to
license the material under the project’s open source license and warrant that
you have the legal authority to do so.__
+If you use AI tools while preparing a contribution, please follow our
[guidelines for AI-assisted contributions](/docs/community/ai-tooling-policy).
+
### Cloning the Apache Wayang™ source code
-If you are interested in working with the newest under-development code or
contributing to Apache Spark development, you can check out the master branch
from Git:
+If you are interested in working with the newest under-development code or
contributing to Apache Wayang development, you can check out the `main` branch
from Git:
```
-# Master development branch
-git clone git://github.com/apache/incubator-wayang.git
+git clone https://github.com/apache/wayang.git
```
Once you’ve downloaded Wayang, you can find instructions for installing and
building it on the [Compiling Apache Wayang](/docs/guide/installation) page.
-### JIRA
-Generally, Wayang uses JIRA to track logical issues, including bugs and
improvements, and uses GitHub pull requests to manage the review and merge of
specific code changes. That is, JIRAs are used to describe what should be fixed
or changed, and high-level approaches, and pull requests describe how to
implement that change in the project’s source code. For example, major design
decisions are discussed in JIRA.
-
-- Find the existing Spark JIRA that the change pertains to.
- - Do not create a new JIRA if creating a change to address an existing
issue in JIRA; add to the existing discussion and work instead
- - Look for existing pull requests that are linked from the JIRA, to
understand if someone is already working on the JIRA
-- If the change is new, then it usually needs a new JIRA. However, trivial
changes, where the what should change is virtually the same as the how it
should change do not require a JIRA. Example: `Fix typos in Foo wayang doc`
-- If required, create a new JIRA:
- - Provide a descriptive Title. “Update web UI” or “Problem in scheduler”
is not sufficient. “Kafka Streaming support fails to handle empty queue in YARN
cluster mode” is good.
- - Write a detailed description. For bug reports, this should ideally
include a short reproduction of the problem. For new features, it may include a
design document.
- - Set required fields:
- - Issue Type. Generally, Bug, Improvement and New Feature are the only
types used in Spark.
- - Priority. Set to Major or below; higher priorities are generally
reserved for committers to set. The main exception is correctness or data-loss
issues, which can be flagged as Blockers. JIRA tends to unfortunately conflate
“size” and “importance” in its Priority field values. Their meaning is roughly:
- - __Blocker__: pointless to release without this change as the
release would be unusable to a large minority of users. Correctness and data
loss issues should be considered Blockers for their target versions.
- - __Critical__: a large minority of users are missing important
functionality without this, and/or a workaround is difficult
- - __Major__: a small minority of users are missing important
functionality without this, and there is a workaround
- - __Minor__: a niche use case is missing some support, but it does
not affect usage or is easily worked around
- - __Trivial__: a nice-to-have change but unlikely to be any
problem in practice otherwise
- - Component
- - Affects Version. For Bugs, assign at least one version that is known
to exhibit the problem or need the change
- - Label. Not widely used, except for the following:
- - `correctness`: a correctness issue
- - `data-loss`: a data loss issue
- - `release-notes`: the change’s effects need mention in release
notes. The JIRA or pull request should include detail suitable for inclusion in
release notes – see “Docs Text” below.
- - `starter`: small, simple change suitable for new contributors
- - Docs Text: For issues that require an entry in the release notes,
this should contain the information that the release manager should include in
Release Notes. This should include a short summary of what behavior is
impacted, and detail on what behavior changed. It can be provisionally filled
out when the JIRA is opened, but will likely need to be updated with final
details when the issue is resolved.
- - Do not set the following fields:
- - __Fix Version__ This is assigned by committers only when resolved.
- - __Target Version__ This is assigned by committers to indicate a PR
has been accepted for possible fix by the target version.
- - Do not include a patch file; pull requests are used to propose the
actual change.
-- If the change is a large change, consider inviting discussion on the issue
at dev@ first before proceeding to implement the change.
+### GitHub issues
+Wayang uses [GitHub issues](https://github.com/apache/wayang/issues) to track
logical issues, including bugs and improvements, and GitHub pull requests to
manage the review and merge of specific code changes. That is, issues describe
what should be fixed or changed and high-level approaches, and pull requests
describe how to implement that change in the project’s source code. Major
design decisions are discussed in issues or on the dev@ mailing list.
-### Pull request
-Before creating a pull request in Apache Wayang, it is important to check if
tests can pass on your branch because our GitHub Actions workflows
automatically run tests for your pull request/following commits and every run
burdens the limited resources of GitHub Actions in Apache Wayang repository.
Below steps will take your through the process.
-
-1. Fork the GitHub repository at https://github.com/apache/incubator-wayang if
you haven’t already
-2. Go to “Actions” tab on your forked repository and enable “Build and test”
and “Report test results” workflows
-3. Clone your fork and create a new branch
-4. Consider whether documentation or tests need to be added or updated as part
of the change, and add them as needed.
- 1. When you add tests, make sure the tests are self-descriptive.
- 2. Also, you should consider writing a JIRA ID in the tests when your
pull request targets to fix a specific issue. In practice, usually it is added
when a JIRA type is a bug or a PR adds a couple of tests to an existing test
class. See the examples below:
-
-``` Java
-@Test
-public void testCase() {
- // WAYANG-12345: a short description of the test
-```
+- Find the existing issue that the change pertains to.
+ - Do not create a new issue if your change addresses an existing one; add
to the existing discussion and work instead.
+ - Look for existing pull requests linked from the issue, to understand if
someone is already working on it.
+- If the change is new, it usually needs a new issue. However, trivial
changes, where what should change is virtually the same as how it should
change, do not require an issue. Example: `Fix typos in Foo docs`.
+- If required, open a new issue:
+ - Provide a descriptive title. “Update web UI” or “Problem in optimizer”
is not sufficient. “Spark platform fails to handle empty input in JDBC source”
is good.
+ - Write a detailed description. For bug reports, this should ideally
include a short reproduction of the problem, the Wayang version, and the
platforms involved. For new features, it may include a design document.
+ - Do not attach a patch file; pull requests are used to propose the actual
change.
+- If the change is a large change, consider inviting discussion on dev@ first
before proceeding to implement it.
-5. Consider whether benchmark results should be added or updated as part of
the change, and add them as needed by Running benchmarks in your forked
repository to generate benchmark results.
-6. Run all tests with in your build to verify that the code still compiles,
passes tests, and passes style checks. If style checks fail, review the Code
Style Guide below.
-7. Push commits to your branch. This will trigger “Build and test” and
“Report test results” workflows on your forked repository and start testing and
validating your changes.
-8. Open a [pull
request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
against the master branch of apache/incubator-wayang. (Only in special cases
would the PR be opened against other branches). This will trigger workflows “On
pull request*” (on the Wayang repo) that will look/watch for successful
workflow runs on “your” forked repository (it will wait if one is running).
- 1. The PR title should be of the form [WAYANG-xxxx][COMPONENT] Title,
where WAYANG-xxxx is the relevant JIRA number, COMPONENT is one of the PR
categories and Title may be the JIRA’s title or a more specific title
describing the PR itself.
- 2. If the pull request is still a work in progress, and so is not ready to
be merged, but needs to be pushed to GitHub to facilitate review, then add
[WIP] after the component.
- 3. Consider identifying committers or other contributors who have worked
on the code being changed. Find the file(s) in GitHub and click “Blame” to see
a line-by-line annotation of who changed the code last. You can add @username
in the PR description to ping them immediately.
- 4. Please state that the contribution is your original work and that you
license the work to the project under the project’s open source license.
-9. The related JIRA, if any, will be marked as “In Progress” and your pull
request will automatically be linked to it. There is no need to be the Assignee
of the JIRA to work on it, though you are welcome to comment that you have
begun work.
+### Pull request
+Before creating a pull request in Apache Wayang, check that the build and
tests pass on your branch. GitHub Actions workflows automatically run the build
and tests for every pull request, and every run burdens the project's shared CI
resources. The steps below take you through the process.
+
+1. Fork the GitHub repository at https://github.com/apache/wayang if you
haven’t already.
+2. Clone your fork and create a new branch from `main`.
+3. Consider whether documentation or tests need to be added or updated as part
of the change, and add them as needed.
+ 1. When you add tests, make sure they are self-descriptive.
+ 2. If your pull request fixes a specific issue, consider referencing the
issue number in the test, for example:
+
+ ```java
+ @Test
+ public void testEmptyInput() {
+ // Regression test for #1234: a short description of the problem
+ ...
+ }
+ ```
+
+4. Consider whether benchmark results should be added or updated as part of
the change, and add them as needed.
+5. Run the build and all tests locally (for example `./mvnw clean install`) to
verify that the code still compiles, passes tests, and passes style and
license-header checks. If style checks fail, review the Code Style Guide below.
+6. Push commits to your branch on your fork.
+7. Open a [pull
request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
against the `main` branch of
[apache/wayang](https://github.com/apache/wayang). This triggers the CI
workflows on the pull request.
+ 1. Give the pull request a short, descriptive title. If it resolves an
issue, write `Fixes #1234` (or `Closes #1234`) in the description so the issue
is linked and closed automatically when the pull request is merged.
+ 2. If the pull request is still a work in progress and not ready to be
merged, but needs to be pushed to GitHub to facilitate review, open it as a
[draft pull
request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests).
+ 3. Consider identifying committers or other contributors who have worked
on the code being changed. Find the file(s) in GitHub and click “Blame” to see
a line-by-line annotation of who changed the code last. You can add @username
in the PR description to ping them.
+8. Comment on the related issue, if any, to let others know you are working on
it. There is no need to be assigned to the issue to work on it.
### The review process
-- Other reviewers, including committers, may comment on the changes and
suggest modifications. Changes can be added by simply pushing more commits to
the same branch.
+- A pull request needs at least one approving review from a committer before
it can be merged; for larger changes, such as new features, API changes, or
changes to the core or optimizer, two committer reviews are recommended. Other
reviewers, including non-committers, may also comment on the changes and
suggest modifications. Changes can be added by simply pushing more commits to
the same branch.
- Lively, polite, rapid technical debate is encouraged from everyone in the
community. The outcome may be a rejection of the entire change.
-- Keep in mind that changes to more critical parts of Spark, like its core and
SQL components, will be subjected to more review, and may require more testing
and proof of its correctness than other changes.
-- Reviewers can indicate that a change looks suitable for merging with a
comment such as: “I think this patch looks good”. Wayang uses the LGTM
convention for indicating the strongest level of technical sign-off on a patch:
simply comment with the word “LGTM”. It specifically means: “I’ve looked at
this thoroughly and take as much ownership as if I wrote the patch myself”. If
you comment LGTM you will be expected to help with bugs or follow-up issues on
the patch. Consistent, judicious u [...]
-- Sometimes, other changes will be merged which conflict with your pull
request’s changes. The PR can’t be merged until the conflict is resolved. This
can be resolved by, for example, adding a remote to keep up with upstream
changes by git remote add upstream
https://github.com/apache/incubator-wayang.git, running git fetch upstream
followed by git rebase upstream/master and resolving the conflicts by hand,
then pushing the result to your branch.
-- Try to be responsive to the discussion rather than let days pass between
replies
-
-### Closing your pull request / JIRA
-- If a change is accepted, it will be merged and the pull request will
automatically be closed, along with the associated JIRA if any
- - Note that in the rare case you are asked to open a pull request against
a branch besides master, that you will actually have to close the pull request
manually
- - The JIRA will be Assigned to the primary contributor to the change as a
way of giving credit. If the JIRA isn’t closed and/or Assigned promptly,
comment on the JIRA.
-- If your pull request is ultimately rejected, please close it promptly
- - … because committers can’t close PRs directly
- - Pull requests will be automatically closed by an automated process at
Apache after about a week if a committer has made a comment like “mind closing
this PR?” This means that the committer is specifically requesting that it be
closed.
-- If a pull request has gotten little or no attention, consider improving the
description or the change itself and ping likely reviewers again after a few
days. Consider proposing a change that’s easier to include, like a smaller
and/or less invasive change.
-- If it has been reviewed but not taken up after weeks, after soliciting
review from the most relevant reviewers, or, has met with neutral reactions,
the outcome may be considered a “soft no”. It is helpful to withdraw and close
the PR in this case.
-- If a pull request is closed because it is deemed not the right approach to
resolve a JIRA, then leave the JIRA open. However if the review makes it clear
that the issue identified in the JIRA is not going to be resolved by any pull
request (not a problem, won’t fix) then also resolve the JIRA.
+- Keep in mind that changes to more critical parts of Wayang, like its core
and optimizer, will be subjected to more review, and may require more testing
and proof of correctness than other changes.
+- Reviewers can indicate that a change looks suitable for merging by approving
the pull request on GitHub or with a comment such as “LGTM”. This means: “I’ve
looked at this thoroughly and take as much ownership as if I wrote the patch
myself”. If you approve a change, you will be expected to help with bugs or
follow-up issues on it. Consistent, judicious approvals are a great way to gain
credibility as a reviewer with the broader community.
+- Sometimes, other changes will be merged which conflict with your pull
request’s changes. The PR can’t be merged until the conflict is resolved. You
can resolve it by adding a remote to keep up with upstream changes (`git remote
add upstream https://github.com/apache/wayang.git`), running `git fetch
upstream` followed by `git rebase upstream/main`, resolving the conflicts by
hand, and then pushing the result to your branch with `git push
--force-with-lease`.
+- Try to be responsive to the discussion rather than let days pass between
replies.
+
+### Closing your pull request / issue
+- If a change is accepted, it will be merged and the pull request will be
closed automatically, along with any issue linked with `Fixes #…`.
+ - Note that in the rare case you are asked to open a pull request against
a branch other than `main`, linked issues are not closed automatically, so
close them manually.
+- If your pull request is ultimately rejected, please close it promptly.
+- If a pull request has gotten little or no attention, consider improving the
description or the change itself, and ping likely reviewers again after a few
days. Consider proposing a change that’s easier to include, like a smaller
and/or less invasive change.
+- If it has been reviewed but not taken up after weeks, after soliciting
review from the most relevant reviewers, or has met with neutral reactions, the
outcome may be considered a “soft no”. It is helpful to withdraw and close the
PR in this case.
+- If a pull request is closed because it is deemed not the right approach to
resolve an issue, leave the issue open. However, if the review makes it clear
that the issue is not going to be resolved by any pull request (not a problem,
won’t fix), then close the issue too.
## Code style guide
Please follow the style of the existing codebase.
-- For Python code, Apache Wayang follows [PEP
8](http://legacy.python.org/dev/peps/pep-0008/) with one exception: lines can
be up to 100 characters in length, not 79.
-- For R code, Apache Wayang follows [Google’s R Style
Guide](https://google.github.io/styleguide/Rguide.xml) with three exceptions:
lines can be up to 100 characters in length, not 80, there is no limit on
function name but it has a initial lower case latter and S4 objects/methods are
allowed.
-- For Java code, Apache Wayang follows [Oracle’s Java code
conventions](http://www.oracle.com/technetwork/java/codeconvtoc-136057.html)
and Scala guidelines below. The latter is preferred.
-- For Scala code, Apache Wayang follows the official [Scala style
guide](http://docs.scala-lang.org/style/).
+- For Java code, Apache Wayang follows the [Google Java Style
Guide](https://google.github.io/styleguide/javaguide.html); the build runs
Checkstyle with the matching rules.
+- For Python code, Apache Wayang follows [PEP
8](https://peps.python.org/pep-0008/).
+- For Scala code, Apache Wayang follows the official [Scala style
guide](https://docs.scala-lang.org/style/).
+- Every source file must start with the Apache License header; the build
checks this automatically.
### If in doubt
If you’re not sure about the right style for something, try to follow the
style of the existing codebase. Look at whether there are other examples in the
code that use your feature. Feel free to ask on the dev@ list as well and/or
ask committers.
## Code of conduct
-The Apache Wayang project follows the Apache Software Foundation Code of
Conduct. The code of conduct applies to all spaces managed by the Apache
Software Foundation, including IRC, all public and private mailing lists, issue
trackers, wikis, blogs, Twitter, and any other communication channel used by
our communities. A code of conduct which is specific to in-person events (ie.,
conferences) is codified in the published ASF anti-harassment policy.
+The Apache Wayang project follows the [Apache Software Foundation Code of
Conduct](https://www.apache.org/foundation/policies/conduct.html). The code of
conduct applies to all spaces managed by the Apache Software Foundation,
including all public and private mailing lists, Slack, issue trackers, wikis,
blogs, social media, and any other communication channel used by our
communities. A code of conduct which is specific to in-person events (i.e.,
conferences) is codified in the published A [...]
We expect this code of conduct to be honored by everyone who participates in
the Apache community formally or informally, or claims any affiliation with the
Foundation, in any Foundation-related activities and especially when
representing the ASF, in any role.
This code is not exhaustive or complete. It serves to distill our common
understanding of a collaborative, shared environment and goals. We expect it to
be followed in spirit as much as in the letter, so that it can enrich all of us
and the technical communities in which we participate.
-For more information and specific guidelines, refer to the Apache Software
Foundation Code of Conduct.
-
-This guide was originally released by [Apache
Spark](https://spark.apache.org/contributing.html), the Apache Wayang project
adapted the guide.
+This guide is adapted from the [Apache Spark contribution
guide](https://spark.apache.org/contributing.html).
diff --git a/docs/community/maturity.md b/docs/community/maturity.md
index 4c3c4f34..03e987e6 100644
--- a/docs/community/maturity.md
+++ b/docs/community/maturity.md
@@ -1,6 +1,6 @@
---
title: Maturity Model
-sidebar_position: 7
+sidebar_position: 10
id: maturity
---
diff --git a/docs/community/repositories.md b/docs/community/repositories.md
index 5dc47857..62bf401c 100644
--- a/docs/community/repositories.md
+++ b/docs/community/repositories.md
@@ -4,21 +4,25 @@ sidebar_position: 2
id: repositories
---
-# Community Hubs
+Apache Wayang is developed in the open on GitHub. Each repository is also
available from the Apache Software Foundation's GitBox service; both are kept
in sync, and contributions are made through pull requests on GitHub.
-### Source Code
+## Source code
-#### Apache Wayang
+| Repository | What it contains | GitHub | ASF GitBox |
+|---|---|---|---|
+| **wayang** | The Wayang source code: core, optimizer, platforms, APIs and
Javadoc | [apache/wayang](https://github.com/apache/wayang) |
[wayang.git](https://gitbox.apache.org/repos/asf/wayang.git) |
+| **wayang-website** | This website: documentation, guides and blog posts |
[apache/wayang-website](https://github.com/apache/wayang-website) |
[wayang-website.git](https://gitbox.apache.org/repos/asf/wayang-website.git) |
-ASF repository :
[https://gitbox.apache.org/repos/asf/incubator-wayang.git](https://gitbox.apache.org/repos/asf/incubator-wayang.git)<br
/>
-GitHub mirror :
[https://github.com/apache/incubator-wayang.git](https://github.com/apache/incubator-wayang.git)
+To get the source code:
-#### Wayang Web Page Repository
+```
+git clone https://github.com/apache/wayang.git
+```
-ASF repository :
[https://gitbox.apache.org/repos/asf/incubator-wayang-website.git](https://gitbox.apache.org/repos/asf/incubator-wayang-website.git)<br
/>
-GitHub mirror :
[https://github.com/apache/incubator-wayang-website.git](https://github.com/apache/incubator-wayang-website.git)
+See [Compiling Apache Wayang](/docs/guide/installation) for how to build it,
and [How to contribute](/docs/community/contribute) before opening a pull
request.
+## Issues, bugs and features
-### Issues, Bugs and Features
+If you have a specific bug to report or feature request, please open an issue
on [GitHub](https://github.com/apache/wayang/issues). Before creating a new
one, search the existing issues to check whether it has already been reported.
-If you have a specific bug to report or feature request, we suggest opening an
issue in [Jira](https://issues.apache.org/jira/projects/WAYANG/issue).
\ No newline at end of file
+The website repository does not have its own issue tracker, so please report
problems with the documentation or website in the same place, or open a pull
request with the fix directly.
diff --git a/docs/community/resources.md b/docs/community/resources.md
deleted file mode 100644
index 53315a97..00000000
--- a/docs/community/resources.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-id: resources
-title: Community Resources & External Coverage
-sidebar_position: 8
----
-
-Apache Wayang thrives because of the conversations, field notes, and
benchmarks that the community shares publicly. To anchor every new visitor in
our core story, treat [What is Wayang?](/docs/introduction/about) as the
**pillar page** for everything related to distributed and federated data
processing with Wayang.
-
-Use the curated resources below to discover third‑party perspectives, then
jump back to the pillar page whenever you need the full technical scope.
-
-## External Articles & Mentions
-
-- [What are the performance implications of multi-engine data
processing?](https://www.novatechflow.com/2025/06/what-are-performance-implications-of.html)
— Novatech Flow (Jun 2025). A practitioner’s view on how Apache Wayang
coordinates distributed engines without sacrificing performance, featuring
federated compute patterns and tuning advice.
-
-## Suggest a Resource
-
-Have you written or found a thoughtful deep dive about Apache Wayang? Open an
issue or PR on [the website
repo](https://github.com/apache/incubator-wayang-website) with the link and a
1–2 sentence description. We prioritize pieces that:
-
-- Explain cross-platform or federated computing scenarios powered by Wayang
-- Include benchmark data, architectural diagrams, or lessons learned from
production usage
-- Link back to the pillar page or other official docs so readers can explore
the project further
-
-Including high-quality external references alongside the official
documentation helps search engines and AI assistants understand how the
community uses Apache Wayang in the broader distributed computing ecosystem.
diff --git a/docs/community/security.md b/docs/community/security.md
index 094bb1dd..e782e374 100644
--- a/docs/community/security.md
+++ b/docs/community/security.md
@@ -1,3 +1,7 @@
+---
+sidebar_position: 11
+---
+
# Wayang Security
The Apache Software Foundation (ASF) and the Apache Wayang community take
security very seriously. Apache Wayang specifically provides robust security
features and actively addresses concerns around potential vulnerabilities. If
you have discovered a vulnerability or have concerns regarding Apache Wayang
security, please immediately contact the security team via email at
[[email protected]](mailto:[email protected]).
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 7b18ae9c..71a897f2 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -30,6 +30,18 @@ title: 'Apache Wayang™',
{
docs: {
sidebarPath: './sidebars.ts',
+ // Insert a "Blog" link into the community sidebar right after
+ // "Repositories", while keeping the rest of it autogenerated.
+ async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args})
{
+ const items = await defaultSidebarItemsGenerator(args);
+ if (args.item.dirName === 'community') {
+ const i = items.findIndex(
+ (it) => it.type === 'doc' && it.id ===
'community/repositories',
+ );
+ items.splice(i + 1, 0, {type: 'link', label: 'Blog', href:
'/blog'});
+ }
+ return items;
+ },
},
blog: {
blogSidebarCount: 'ALL',
@@ -85,25 +97,10 @@ title: 'Apache Wayang™',
label: 'Developers',
},
{
- type: 'dropdown',
- label: 'Community',
+ type: 'docSidebar',
+ sidebarId: 'communitySidebar',
position: 'right',
- items: [
- {
- label: 'Blog',
- to: '/blog/',
- },
- {
- type: 'doc',
- docId: 'community/resources',
- label: 'Community Resources',
- },
- {
- type: 'docSidebar',
- sidebarId: 'communitySidebar',
- label: 'Project',
- },
- ]
+ label: 'Community',
},
{
type: 'dropdown',
diff --git a/sidebars.ts b/sidebars.ts
index 3da34681..59746da4 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -16,6 +16,8 @@ const sidebars: SidebarsConfig = {
startSidebar: [{type: 'autogenerated', dirName: 'start'}],
introductionSidebar: [{type: 'autogenerated', dirName: 'introduction'}],
guideSidebar: [{type: 'autogenerated', dirName: 'guide'}],
+ // The Blog link is inserted after Repositories by sidebarItemsGenerator
+ // in docusaurus.config.ts.
communitySidebar: [{type: 'autogenerated', dirName: 'community'}],
// But you can create a sidebar manually