Skip to content

Latest commit

 

History

History
249 lines (166 loc) · 9.41 KB

CONTRIBUTING.md

File metadata and controls

249 lines (166 loc) · 9.41 KB
Raw

Contributing

We accept all kinds of contributions:

  1. Reviewing a PR
  2. Opening an issue by describing what problem you see that we need to fix
  3. Opening a PR if you see a typo, broken link, or any other minor changes.

To include a new guide or documentation content, please open an issue first so we can discuss in more detail what needs to be done. We use Issues to track our tasks. Please include a good title and thorough description.

Including a new guide

  1. Open an issue provide a description and link any pull-requests related to the guide.
  2. Write the guide.
  3. Add a link to the guide in serverlessworkflow/modules/ROOT/nav.adoc
  4. Add a card for the guide in serverlessworkflow/modules/ROOT/pages/index.adoc
  5. Submit a PR

Opening an Issue

  1. Make sure to add a good summarizing title and thorought description of the guide you plan to add.
  2. Clearly describe in which parent category you will publish the guide.
  3. Ensure there are linked contribution realated to the guide, so that the Reviewer is able to understand the source.

Following up a code change

If your PR is to update a guide with a change you made in Kogito project code base, you don't need to create a new issue just to update the documentation.

Use the same issue and make sure that your branches are called kie-kogito-docs-#NNNN where NNNNN is the issue number.

For the documentation review, do the same step as described in the item number 4 in the previous section: open an issue and use proper label.

Basic Conventions

As a general rule of thumb, look at the published documentation to have an idea of the writing style, format, and organization.

UI Elements

When you write about an item displayed in a graphical user interface, match the capitalization and spelling of the item, and bold the term in your writing. For example:

❌ Click Save As... and then type a file name.
❌ Click save as and then type a file name.
✅ Click Save As and then type a file name.

Spelling

In general, use US English spelling in all publications.

❌ Labelled
✅ Labeled

❌ Fulfil
✅ Fulfill

Headings

For a task procedure heading, use a gerund or imperative verb form. Use a gerund for a high-level task such as installing, administering, or troubleshooting.

❌ Create a data load activity
✅ Creating a data load activity

Ensure that the typographic style is consistent for each heading level in your content.

❌ Mapping assets by using the cf map-route command
✅ Mapping assets by using the cf map-route command

Always use the following convention when creating a new article for the main heading:

= Kogito Guide Title (first-level heading)
== Example section (second-level heading)
...

Writing style

Use present tense.

❌ When you open the latch, the panel will slide forward.
✅ When you open the latch, the panel slides forward.

Use active voice.

❌ Passive: The Limits window is used to specify the minimum and maximum values.
✅ Active: In the Limits window, specify the minimum and maximum values.

Use second person (you). Avoid first person (I, we, us). Be gender-neutral. Use the appropriate tone. Write for a global audience.

❌ We can add a model to the project that we created in the previous step.
✅ You can add a model to the project that you created in the previous step.

❌ It is important that the file be saved...
✅ Important: Save the file...

Capitalization

In general, use a lowercase style in text and use sentence-style capitalization for headings, titles, labels, banners, and similar elements.

✅ Business models
✅ Creating Boolean expressions
✅ Planning network architectures
✅ Properties and settings for printing
✅ Requirements for Linux and UNIX operating systems

Quick Reference

Page cross-reference

  • To refer a page in same module
    • xref:file_name.adoc[optional text]
    • Example: xref:index.adoc[Home]
  • To refer a page in different module
    • xref:module_name:file_name.adoc[optional text]
    • Example: xref:getting-started:create-file.adoc[Create file]
  • To refer a page on other component
    • xref:compnent_name:module_name:file_name.adoc[optional text]
    • Example: xref:contribution-guide:getting-started:create-file.adoc[Create file]

More details regarding xref at the Antora documentation xref section.

Embedding a page in current page

  • Embed page in same module
    • include::./gear.adoc[optionl text]
  • Embed a page from another module or component version
    • include::module:file-coordinate-of-target-page.adoc[]
    • include::version@component:module:file-coordinate-of-target-page.adoc[]
    • include::component:module:file-coordinate-of-target-page.adoc[]

More details at Antora documentation.

Assigning attributes on a site

You can create attributes in {project_root}/{component_name}/antora.yml file. These attributes can be use anywhere in that module.

asciidoc:
  attributes:
    :example_url: https://www.myexample.com

More details at Antora documentation

Using Dry URLs for Links

You should assign the URL to a short, easy to remember attribute. For example:

:issues_url: https://github.com/asciidoctor/asciidoctor/issues`

// later in the document

Submit bug fixes to the link:{issues_url}[issue tracker]

Every attribute which consists of a URL must have the suffix _url. Use underscore (_) to separate words.

More details at the AsciiDoc Documentation

Creating new category for docs

In the same component to add a new category, create a new folder with a category name under the modules/ROOT/pages/ folder of the component.

For example, to add a page hello.adoc you can create a page at modules/ROOT/pages/hello/hello.adoc.

Storing Assets

Assets relating to a page should be stored at modules/ROOT/assets under the given category.

For example, to add an image for hello.adoc page, put the image in modules/ROOT/assets/images/hello/image_name.png

Creating switch tabs

You can create tabs using the format below:

[tabs]
====
Tab A::
+
[source,shell]
--
Contents of tab A.
--
Tab B::
+
[source,java]
--
Contents of tab B.
--
====

Adding an admonitions

Use the following format:

[NOTE]
====
Content
====

Similarly, you can have other admonitions:

  • TIP
  • IMPORTANT
  • CAUTION
  • WARNING

More details at Antora documentation.

Generating Release Notes for Serverless Workflow

  1. You can retrieve all changes in the release page of each repository of the project:

    Replace {version} with the given core version, for example 1.41.0.Final.
    Replace {version_without_Final} with the given cloud version, for example 1.41.0.

    You should also get JIRA issues with KOGITO and DROOLS projects as well as issues coming from the kie-issues repository. An example of a filter for KOGITO JIRA project:

    project = Kogito and fixVersion = <version> and component in ("Serverless Workflow Editor", "Serverless Workflow Engine") AND status in (Resolved, Done)  and type != Sub-task and type != Epic

    Replace <version> with the given version, for example 1.41.0.Final.

  2. Update the page release_notes.adoc

  3. Align with the team what should be under "Notable changes"

  4. Add the rest to "Other Changes and Bug Fixing".

  5. Open a PR in the target branch version, not main

  6. Add one member from each squad to review

Configuring the Domain

Don't use the GH Pages Settings, but change the CNAME file instead. This is because the GH Settings page will change the branch gh-pages directly, whereas we have a CI workflow to build the website. Once we run the CI, it will override anything within build/site. Preserving the CNAME file there guarantees that the CI won't override it.

Useful Resources