5032901dfc
### _Why are the changes needed?_ Guidelines for Document and Code Contributions. - code style - documentation style - quick starts - sphinx-copybutton for copy button in code blocks - add kind:minor,help wanted,good first issue to doc issue template ### _How was this patch tested?_ - [ ] Add some test cases that check the changes thoroughly including negative and positive cases if possible - [x] Add screenshots for manual tests if appropriate <img width="1325" alt="image" src="https://user-images.githubusercontent.com/8326978/234193368-473e2a1d-2deb-4d91-901a-19cea58a489b.png"> - [x] [Run test](https://kyuubi.readthedocs.io/en/master/develop_tools/testing.html#running-tests) locally before make a pull request Closes #4768 from yaooqinn/guide. Closes #4768 3a0bd395b [Kent Yao] Update docs/contributing/doc/build.rst 8fe4f6d14 [Kent Yao] Update docs/contributing/doc/build.rst a753bdde5 [Kent Yao] Guidelines for Document and Code contributions f8393fe8d [Kent Yao] Guidelines for Document and Code contributions 8f2d3ce82 [Kent Yao] Guidelines for Document and Code contributions 4f3a2128b [Kent Yao] Guidelines for Document and Code contributions Authored-by: Kent Yao <yao@apache.org> Signed-off-by: Cheng Pan <chengpan@apache.org>
117 lines
4.0 KiB
ReStructuredText
117 lines
4.0 KiB
ReStructuredText
.. Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
.. http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
.. Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
Get Started
|
|
===========
|
|
|
|
.. image:: https://img.shields.io/github/issues/apache/kyuubi/kind:documentation?color=green&logo=gfi&logoColor=red&style=for-the-badge
|
|
:alt: GitHub issues by-label
|
|
|
|
|
|
Trivial Fixes
|
|
-------------
|
|
|
|
For typos, layout, grammar, spelling, punctuation errors and other similar issues
|
|
or changes that occur within a single file, it is acceptable to make edits directly
|
|
on the page being viewed. When viewing a source file on kyuubi's
|
|
`Github repository`_, a simple click on the ``edit icon`` or keyboard shortcut
|
|
``e`` will activate the editor. Similarly, when viewing files on `Read The Docs`_
|
|
platform, clicking on the ``suggest edit`` button will lead you to the editor.
|
|
These methods do not require any local development environment setup and
|
|
are convenient for making quick fixes.
|
|
|
|
Upon completion of the editing process, opt the ``commit changes`` option,
|
|
adhere to the provided instructions to submit a pull request,
|
|
and await feedback from the designated reviewer.
|
|
|
|
Major Fixes
|
|
-----------
|
|
|
|
For significant modifications that affect multiple files, it is advisable to
|
|
clone the repository to a local development environment, implement the necessary
|
|
changes, and conduct thorough testing prior to submitting a pull request.
|
|
|
|
|
|
`Fork`_ The Repository
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Clone The Forked Repository
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block::
|
|
:caption: Clone the repository
|
|
|
|
$ git clone https://github.com/your_username/kyuubi.git
|
|
|
|
Replace "your_username" with your GitHub username. This will create a local
|
|
copy of your forked repository on your machine. You will see the ``master``
|
|
branch if you run ``git branch`` in the ``kyuubi`` folder.
|
|
|
|
Create A New Branch
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block::
|
|
:caption: Create a new branch
|
|
|
|
$ git checkout -b guide
|
|
Switched to a new branch 'guide'
|
|
|
|
Editing And Testing
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Make the necessary changes to the documentation files using a text editor.
|
|
`Build and verify`_ the changes you have made to see if they look fine.
|
|
|
|
.. note::
|
|
:class: dropdown, toggle
|
|
|
|
Create A Pull Request
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Once you have made the changes,
|
|
|
|
- Commit them with a descriptive commit message using the command:
|
|
|
|
.. code-block::
|
|
:caption: commit the changes
|
|
|
|
$ git commit -m "Description of changes made"
|
|
|
|
- Push the changes to your forked repository using the command
|
|
|
|
.. code-block::
|
|
:caption: push the changes
|
|
|
|
$ git push origin guide
|
|
|
|
- `Create A Pull Request`_ with a descriptive PR title and description.
|
|
|
|
- Polishing the PR with comments of reviews addressed
|
|
|
|
Report Only
|
|
-----------
|
|
|
|
If you don't have time to fix the doc issue and submit a pull request on your own,
|
|
`reporting a document issue`_ also helps. Please follow some basic rules:
|
|
|
|
- Use the title field to clearly describe the issue
|
|
- Choose the documentation report template
|
|
- Fill out the required field in the documentation report
|
|
|
|
.. _Home Page: https://kyuubi.apache.org
|
|
.. _Fork: https://github.com/apache/kyuubi/fork
|
|
.. _Build and verify: build.html
|
|
.. _Create A Pull Request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
|
|
.. _reporting a document issue: https://github.com/apache/kyuubi/issues/new/choose |