Skip to content
Permalink
Browse files
HOP-2971, HOP-2972, HOP-2973
  • Loading branch information
bamaer committed Jun 19, 2021
1 parent 132cdc7 commit 49dd30421329233bcd37d6be6749e770b09ef5cc
Show file tree
Hide file tree
Showing 6 changed files with 42 additions and 41 deletions.
@@ -13,10 +13,10 @@ Contributing to Hop goes beyond writing code for the project. Below, we list dif
|Area |Further Information
|Report a Bug|To report a problem with Hop, open Hop’s https://issues.apache.org/jira/projects/HOP/issues[Jira ,window=_blank], log in if necessary, and click on the "+" in the left side bar (Shortcut "c").
Please give detailed information about the problem you encountered and, if possible, add a description that helps to reproduce the problem. For more information go to our link:../contribution-guides/jira-guide/[info] page.
|Contribute Code|Read the link:../contribution-guides/code-contribution-guide/[Code Contribution Guide] (Work in progress)
|Help With Code Reviews|Read the link:../contribution-guides/code-review-guide/[Code Review Guide] (Work in progress)
|Help Prepare a Release|Read the link:../contribution-guides/release-contribution-guide/[Release Review Guide] (Work in progress)
|Contribute Documentation|Read the link:../contribution-guides/documentation-contribution-guide/[Documentation Contribution Guide] (Work in progress)
|Contribute Code|Read the link:../contribution-guides/code-contribution-guide/[Code Contribution Guide]
|Help With Code Reviews|Read the link:../contribution-guides/code-review-guide/[Code Review Guide]
|Help Prepare a Release|Read the link:../contribution-guides/release-contribution-guide/[Release Review Guide]
|Contribute Documentation|Read the link:../contribution-guides/documentation-contribution-guide/[Documentation Contribution Guide]
|Translate Hop|Read the link:../contribution-guides/translation-contribution-guide/[Translation Contribution Guide]
|Support Hop Users|
- Join us on our https://chat.project-hop.org[Mattermost ,window=_blank] server and answer questions
@@ -25,11 +25,11 @@ Please give detailed information about the problem you encountered and, if possi

- Check the latest issues in Jira for tickets which are actually user questions

|Improve the Website|Read the link:../contribution-guides/website-contribution-guide/[Website Contribution Guide] (Work in progress)
|Improve the Website|Read the link:../contribution-guides/website-contribution-guide/[Website Contribution Guide]
|Spread the Word about Hop|
- Organize or attend a Hop Meetup

- Contribute to the Hop blog (comming soon)
- Contribute to the Hop blog (coming soon)


2+|Any other questions? Reach out on the Hop https://chat.project-hop.org[chat ,window=_blank] to get help.
@@ -55,29 +55,7 @@ Committers are community members that have write access to the project’s repos

There is no strict protocol for becoming a committer or PMC member. Candidates for new committers are typically people that are active contributors and community members.

Candidates for new committers are suggested by current committers or PMC members, and voted upon by the PMC.
As in all Apache projects, candidates for new committers are suggested by current committers or PMC members, and voted upon by the PMC.

If you would like to become a committer, you should engage with the community and start contributing to Apache Hop in any of the above ways. You might also want to talk to other committers and ask for their advice and guidance.
If you would like to become a committer, we encourage you to engage with the community and start contributing to Apache Hop in any possible way. Contributions come in many shapes and forms, and the Hop community appreciates every contributor and contribution. You might also want to talk to other committers and ask for their advice and guidance.

=== What are we looking for in Committers
Being a committer means being recognized as a significant contributor to the project (community or technology), and having the tools to help with the development. Committer candidates are community members who have made good contributions over an extended period of time and want to continue their contributions.

Community contributions include helping to answer user questions on the mailing list, verifying release candidates, giving talks, organizing community events, and other forms of evangelism and community building. The “Apache Way” has a strong focus on the project community, and committers can be recognized for outstanding community contributions even without any code contributions.

Code/technology contributions include contributed pull requests (patches), design discussions, reviews, testing, and other help in identifying and fixing bugs. Especially constructive and high quality design discussions, as well as helping other contributors, are strong indicators.

While the prior points give ways to identify promising candidates, the following are “must haves” for any committer candidate:
- Being community minded: The candidate understands the meritocratic principles of community management. They do not always optimize for as much as possible personal contribution, but will help and empower others where it makes sense.
- We trust that a committer candidate will use their write access to the repositories responsibly, and if in doubt, conservatively. Hop is a big system, and it is important that committers are aware of what they know and what they don’t know. In doubt, committers should ask for a second pair of eyes rather than commit to parts that they are not well familiar with. (Even the most seasoned committers follow this practice.)
- They have shown to be respectful towards other community members and constructive in discussions.

==== What are we looking for in PMC members
The PMC is the official controlling body of the project. PMC members “must” be able to perform the official responsibilities of the PMC (verify releases and growth of committers/PMC). We “want” them to be people that have a vision for Hop, technology and community wise.

For the avoidance of doubt, not every PMC member needs to know all details of how exactly Hop’s release process works (it is okay to understand the gist and how to find the details). Likewise, not every PMC member needs to be a visionary. We strive to build a PMC that covers all parts well, understanding that each member brings different strengths.

Ideally, we find candidates among active community members that have shown initiative to shape the direction of Hop (technology and community) and have shown willingness to learn the official processes, such as how to create or verify for releases.

A PMC member is also a committer. Candidates are already committers or will automatically become also a committer when joining the PMC. Hence, the “What are we looking for in committers?” also applies to PMC candidates.

A PMC member has a lot of power in a project. A single PMC member can block many decisions and generally stall and harm the project in many ways. We hence must trust the PMC candidates to be level-headed, constructive, supportive, and willing to “disagree and commit” at times.
@@ -18,7 +18,7 @@ WARNING: Just like code, documentation is never done. We're eager to find out ho
The Hop documentation and website content are written in Asciidoc. Asciidoc is a lightweight markup language which can be translated to HTML.

In order to update or extend the documentation you have to modify the Asciidoc (.adoc) files.
For more information on Asciidoc check out http://asciidoc.org/[this] website.
For more information on Asciidoc check out http://asciidoc.org/[asciidoc.org].

The Hop docs and website content are built using the https://antora.org[Antora] framework.

@@ -29,7 +29,7 @@ video::BAJ8F7yQz64[youtube]

== anchor:doc-types[]Types of documentation

Apache Hop has multiple types of documentation, each type is directed to a different audience and covers other use cases. We are maintaining a user manual which contains basic and more advanced instructions on how to use and set up Hop.
Apache Hop has multiple types of documentation for different audiences, covering specific topics and use cases. We have a user manual for basic and more advanced instructions on how to install, use configure Apache Hop.

User manual::
The goal for the user manual is to give a general feeling to how the application works, which transforms and actions are available and a guide on how to use them. A default template is used to explain how transforms and actions work, an Archetype is included in the repository to use as a template.
@@ -41,30 +41,51 @@ API documentation::
This is code documentation and only needed when you want to explore the internals of Hop or contribute code.


== anchor:get-docs[]Get the documentation sources
== Work on the documentation directly from the Hop website

Depending on the type of documentation the Apache Hop documentation is maintained in the separate git repository as the code base.
Every documentation page on the Hop website has a 'Edit this page' button like the one below.

image:/img/doc-contrib-edit-this-page.png[Edit this page, width="35%"]

If you click on this page, you'll be taken directly to the github editor for that page.

After you've made the changes you want to make, add a description for your changes and click 'Proposed changes'.

image:/img/doc-contrib-propose-changes.png[Propose Changes, width="55%"]

Review the entries in the pull request template and click 'Create pull request'.

image:/img/doc-contrib-create-pr.png[Create Pull Request, width="55%"]

Once your pull request has been reviewed, accepted and merged, the Hop build system will run a couple of checks and tests and the website needs to be rebuilt with your changes.

TIP: The pull request review and merge is a manual process. Even though it usually only takes a couple of hours at most, this process can not be fully automated, so don't expect your changes to appear immediately.


== anchor:get-docs[]Work on the documentation asciidoc

All Apache Hop documentation is maintained in the same git repository as the code base.

=== User manual and Technical documentation

The easiest way to contribute documentation is to fork Hop’s repository on GitHub into your own GitHub account by clicking on the fork button at the top right. If you have no GitHub account, you can create one for free.
The easiest way to contribute documentation is to fork https://github.com/apache/incubator-hop[Hop’s repository] on GitHub into your own GitHub account by clicking on the fork button at the top right. If you have no GitHub account, you can create one for free.

Next, clone your fork to your local machine.

[source,shell]
git clone https://github.com/<your-user-name>/hop-doc.git
git clone https://github.com/<your-user-name>/incubator-hop.git

The user manual documentation is located in the hop-user-manual/ subdirectory.
The technical documentation is located in the hop-technical-documentation/ subdirectory.
The user manual documentation is located in the docs/hop-user-manual/ subdirectory.
The technical documentation is located in the docs/hop-tech-manual/ subdirectory.


=== API documentation
To contribute to the API and code documentation create a fork of Hop's code repository.

[source,shell]
git clone https://github.com/<your-user-name>/hop.git
git clone https://github.com/<your-user-name>/incubator-hop.git

The API documentation is located in the docs/ subdirectory
The API documentation is located in the docs/hop-dev-manual subdirectory


== anchor:before-start[]Before you start start working on the documentation...
@@ -91,6 +112,6 @@ Push your committed contribution to your fork of the Hop repository at GitHub.
[source,shell]
git push origin myBranch

Go to the website of your repository fork (`https://github.com/<your-user-name>/hop-doc`) and use the “Create Pull Request” button to start creating a pull request. Make sure that the base fork is hop master and the head fork selects the branch with your changes. Give the pull request a meaningful description and submit it.
Go to the website of your repository fork (`https://github.com/<your-user-name>/incubator-hop`) and use the “Create Pull Request” button to start creating a pull request. Make sure that the base fork is hop master and the head fork selects the branch with your changes. Give the pull request a meaningful description and submit it.

It is also possible to attach a patch to a Jira issue.
@@ -53,6 +53,8 @@ Vote! After you've reviewed a release candidate, submit your vote to the mailing

Reviewing and voting for releases (or release candidates) is an important and valuable contribution, every vote matters!

Check the detailed https://hop.apache.org/dev-manual/latest/apache-release/checking-a-release.html[checking a release] guide.

== What is the voting process?

=== Procedure
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 49dd304

Please sign in to comment.