Skip to content

Latest commit

 

History

History
249 lines (166 loc) · 9.36 KB

CONTRIBUTING.md

File metadata and controls

249 lines (166 loc) · 9.36 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 JIRA to track our tasks, so the issue is likely to turn into a JIRA issue.

Including a new guide

  1. Open a JIRA issue and add a sub-task for Doc review.
  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

Opening a JIRA Issue

  1. Make sure to add a description of the guide you plan to add followed by the [Kogito Guides] prefix
  2. Clearly describe in which parent category you will publish the guide
  3. Create a sub-task with the title [Docs Review][Kogito Guides] - JIRA Title so that the Content Team can review your guide.
  4. After all SMEs have reviewed and approved your guide, change the status of the sub-task to "Pull Request Sent" by adding the PR link to the sub-task JIRA. This way, the documentation team will be notified and will review your PR.

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 JIRA just to update the documentation.

Use the same JIRA issue and make sure that your branch is called kogito-NNNNN where NNNNN is the JIRA number. This way, our automation will work and link all the PRs together among every repository impacted by your change.

For the documentation review, do the same step as described in the item number 4 in the previous section: open a sub-task in the JIRA issue.

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