kyma-project / community Goto Github PK
View Code? Open in Web Editor NEWProvides general guidelines, contributing, and maintaining rules for all who add content to Kyma.
Home Page: https://kyma-project.io/community/
License: Apache License 2.0
Provides general guidelines, contributing, and maintaining rules for all who add content to Kyma.
Home Page: https://kyma-project.io/community/
License: Apache License 2.0
Confirm these statements before you submit the issue:
Description
Reasons
Every documentation topic must follow https://github.com/kyma-project/community/blob/master/guidelines/content-guidelines/content-strategy.md#documentation-types and all those types must have templates which make it much easier for anybody to contribute content
Description
Since the decision-making process has changed, the "governance.md" document contains outdated diagram illustrating the process.
Correct the diagram and save the updated version in the svg format according to the guidelines.
Hi,
Can you, please, add the Stack Overflow Icon to the footer and community section on the Kyma Website?
The relevant icons are in Zeplin.
Thanks!
Ana
Description
Rewrite the diagram in https://github.com/kyma-project/community/blob/master/issues-workflow.md to match our guidelines: https://github.com/kyma-project/community/blob/master/guidelines/content-guidelines/diagrams.md.
SVG as a source is enough.
Reasons
It does not match the guidelines.
Confirm these statements before you submit the issue:
Description
Reasons
Every documentation topic must follow https://github.com/kyma-project/community/blob/master/guidelines/content-guidelines/content-strategy.md#documentation-types and all those types must have templates which make it much easier for anybody to contribute content
Description
Update content guidelines with information to use short command line arguments (-n
instead of --namespace
) in the documentation whenever possible, unless it causes confusion in a given context. For example, short ones can be easily misinterpreted as they differ between tools, e.g. helm -n == helm --name != helm --namespace while kubectl -n == kubectl --namespace. In such a situation, the context should be explained in a given doc.
Reasons
A unified standard for command line arguments.
Description
Update the optional doc section in the content-strategy.md
document with information on a new type of documents called Examples. Mention that it should be used optionally in the official kyma docs under kyma/docs
.
Related issues
It relates to the issue #1730
and should be done as a follow-up to it.
Description
Add these two bullet points to the Terminology section in the Style and Standards document to mention that we should use:
Description
Update the content strategy document to include the Installation document type as an additional, optional, document type. Describe the type and its purpose in short.
Reasons
Since the number of Kyma installation guides is (and will be) growing we would like to expose those documents more and separate them from other Getting Started guides or Details docs on the installation topic. Thus, an idea for a new type was proposed and agreed on as part of that issue.
Description
Reasons
This is to increase accuracy and better definitions of security related issues
Create a document that contains information about the release process.
The input from @crabtree:
Description
The first release of kyma-project is out. In order to make a next release less painfull several actions should be taken:
Confirm these statements before you submit the issue:
Description
Currently it is hard to figure out what resources were created by controllers for Kyma CRDs. For example the API controller creates an ingress resource but it is hard to identify that it belongs to an API resource (you need to know the naming convention).
Without an easy way to recognize system resources that are managed by controllers (creation and deletion) we have the following issues
Suggestion
whenever a kyma controller creates a resource in consequence of a kyma CRD resource, that resource will be enriched with all needed ownerReference attributes, see kubernetes guide. That needs to be documented in the guide for CRD development.
If done, please think about creating follow up tickets for adjusting existing controllers.
Confirm these statements before you submit the issue:
Changes required:
Created on 2018-12-05 by Szymon Janota (@sjanota)
Name | Description |
---|---|
Title | How to run Kyma with Knative |
Ultimate decision maker(s) | Kyma Council |
Due date | 2018-12-20 |
Input provider(s) | @kubadz @Abd4llA @sjanota |
Group(s) affected by the decision | WG Knative Integration |
Decision type | Binary |
Earliest date to revisit the decision | 2019-01-06 |
Affected decisions | None |
One of the features that is currently being implemented in Kyma is the integration with Knative. It must be established how to run Kyma and Knative in a single Kubernetes cluster.
The following factors need to be taken into consideration:
With these criteria in mind, solutions must be chosen for these problems:
Each of these problems can be solved several ways. The possible solutions are discussed in the next section.
Kyma and Knative are both installed in their own Namespaces, so they are not conflicting with each other directly. The only component they share is Istio. Kyma introduces several changes to the default Istio installation, whereas Knative does not modify Istio in an intrusive manner. This allows Knative to work with the Kyma version of Istio without any problems. Knative runs on top of Istio, but uses its own ingress gateway, while Kyma uses the Istio default Gateway. The Gateways are configured so that they can be accessed under different Services. Both ingress gateways and their configurations are installed in the istio-system
Namespace. There are two approaches to making both tools accessible:
Do not change the network configuration. Acces Kyma and Knative through their respective default ingress gateways. This solution was proved to be working by @kubadz in kyma-project/kyma#1643
Route all traffic through the Knative ingress gateway, abandon the default Kyma ingress gateway. This solution was proved to be working by @sjanota in kyma-project/kyma#1598.
Advantages:
Disadvantages:
The "batteries included" principal is one of the most important ones for Kyma. That's why Knative integration needs to be available without requiring the users to install additional components on their own. Because of its dependency on Istio, Knative must be installed by the Kyma installer after Istio.
Knative team does not provide Helm charts for their releases. Instead, they provide yaml
files containing all of the resources. Possible ways to integrate Knative installation into the Kyma installer:
Create a Kubernetes job which installs Knative from the yaml
file and verifies the installation, just like Helm would do. This job also adds required customizations.
Advantages:
Disadvantages:
Create a chart which embeds Knative yaml
files. Required customisations are added as generic parameters to the chart or changed using existing tools such as overrides or the istio-patch.
Advantages:
Disadvantages:
Version URLs to specific versions of Knative.
Advantages:
yaml
file are not maintained in KymaDisadvantages:
Version all yaml
files within the Kyma repository
Advantages:
Disadvantages:
Proposed solution is to use the Knative ingress gateway as it allows for a better integration with Knative and makes cluster management easier. The other ingress gateway will still be deployed, but will remain unexposed and unused. As this solution requires changes in both Knative and Kyma deployments, extensibility is the main concern when thinking about installation. Therefore the chosen approach is to embed Knative in the chart. Packing Knative into a chart format eliminates the possibility to version only URLs. Instead, all of the required yaml
files must be added to Kyma.
Installing Kyma with Knative is optional. Installation can be enabled with the global.knative global installer override paired with a boolean value. Kyma without Knative installed will continue working as before.
Approved
Proposed on 2018-12-06
Advantages:
yaml
files. This is important from the eventing and serverless perspective.Disadvantages:
yaml
files to another.Description
Add information on the new formatting of CRs to the content guidelines.
The accepted format is: {Name} custom resource
Reasons
TWs' decision
The table with the templates may be a bit unclear when it comes to the README.md documents. Improve the table so that it makes it clear when to use a given README template.
Confirm these statements before you submit the issue:
Description
As a follow-up task, adjust the existing Overview documents to the template.
Reasons
Every documentation topic must follow https://github.com/kyma-project/community/blob/master/guidelines/content-guidelines/content-strategy.md#documentation-types and all those types must have templates which make it much easier for anybody to contribute content
Description
Decide what should be the order of document types that should be used consistently in all component docs under kyma/docs
.
content-strategy.md
accordingly. Consult the choice with other TWs (it can be done through comments in the pull request).Getting Started
type of docs into Tutorial
, as agreed on the SIG Content.Reasons
Consistency in docs
Description
Reasons
Description
The guidelines do not provide any information on whether to capitalize "lambda/function" terms or not. Make a research on whether to capitalize those terms or not and update the guidelines.
Decision
We should capitalize Function when it refers to the Kubernetes resource. Otherwise, it should be written in lowercase. We agreed not to capitalize "lambda" on one of the SIG Core meetings.
AI:
Add "Function" to the list of capitalized terms in the guidelines.
Description
Now that all PRs should have labels of the area(s) they refer to, the below guidelines require an update:
https://github.com/kyma-project/community/blob/master/git-workflow.md#contribute
https://github.com/kyma-project/community/blob/master/CONTRIBUTING.md#contribution-process
Update them with the info / or a step that a proper label should be assigned to each and every PR on every repo - only then they are included in the changelog.
Description
When I go to page: https://kyma-project.io/docs/components/serverless#
scroll down to the bottom and click the service catalog hyperlink:
it does not work:
Expected result
The document page for service catalog is displayed.
Actual result
Confirm these statements before you submit the issue:
Description
Since there were changes in the PR template introduced by this PR: [https://github.com//pull/12,] TWs need to adjust other templates to those changes.
community
repository, under /.github/pull-request-template.md
location.Confirm these statements before you submit the issue:
- [ ] I have searched open and closed issues for duplicates.
- [ ] I have read the contributing guidelines.
---
The replacement of the checkboxes with hidden descriptions needs to be done on all repos and in the repository-template that is in the community repo. There are three issue templates on each repo:
/.github/issue-template.md
/.github/ISSUE_TEMPLATE/bug-report.md
/.github/ISSUE_TEMPLATE/feature-request.md
Created on | Created by |
---|---|
2018-12-17 | Marco Bebway (@marcobebway) |
Purpose
Having the option to run kyma-eventing on top of knative-eventing.
Use-cases
Design
Kyma is installed on top of Knative and using knative-eventing abstraction to publish and deliver messages:
Development
Create two new apps inside the event-bus component codebase, one for the publish-knative app and the other for subscription-controller-knative app.
Note: The publish-knative app should expose a publish API to publish messages from kyma to knative-eventing. The publish API should expect two required parameters the event-type and the source-id.
Note: The subscription-controller-knative app should act upon the events coming from Kubernetes regarding the Kyma subscription-crd and the Kyma event-activation-crd, and it should create a corresponding Knative subscription. In addition, it should send requests to the Knative provisioner controller to store the subscriptions in the underlying messaging system backend.
Note: We need to come up with a convention to map kyma-subscription(s) to knative-subscription(s).
Deployment
Move event-bus helm chart from kyma/resources/core/charts/event-bus/ to kyma/resources/event-bus.
Create a new helm chart for event-bus-knative component inside kyma/resources/event-bus-knative.
Move nats-streaming helm chart from kyma/resources/core/charts/event-bus/charts/nats-streaming to kyma/resources/nats-streaming. As a constraint by Knative, the nats-streaming messaging system should not be installed in the knative-eventing namespace. Also it should be installed in a namespace which is istio-injection enabled. In general, it can be installed in the kyma-system namespace which is istio-injection enabled.
Create a new helm chart for nats-streaming-provisioner under kyma/resources/nats-streaming-provisioner. As a constraint by Knative, the nats-streaming-provisioner must be installed in the knative-eventing namespace. Also it should have a dependency entry in the kyma/resources/core/charts/event-bus-eventing/requirements.yaml to install it when Kyma runs on top of Knative.
The new directory structure should look like this:
.
├── kyma/
│ └── resources/
│ ├── .
│ ├── event-bus/
│ ├── event-bus-knative/
│ ├── nats-streaming/
│ ├── nats-streaming-provisioner/
│ ├── .
Update the template files kyma/installation/resources/installer-cr.yaml.tpl and kyma/installation/resources/installer-cr-cluster.yaml.tpl to include the components nats-streaming and event-bus under the spec/components.
Update the template files kyma/installation/resources/installer-cr-knative.yaml.tpl and kyma/installation/resources/installer-cr-cluster-knative.yaml.tpl to include the components nats-streaming, nats-streaming-provisioner and event-bus-knative under the spec/components.
Update the knative charts inside kyma/resources/knative/ to use the proper knative version that has the nats-streaming-provisioner supported.
Design decisions
Installation
Description
The Style and standards guide contains a confusing passage about the terminology of "for example".
Expected result
Clarify that "for example" should be used instead of "e.g.":
- "for example", not "e.g."
✅ There are many animals in the zoo. For example: lions, elephants, and zebras.
⛔️ There are many animals in the zoo, for example: lions, elephants, and zebras.
⛔️ There are many animals in the zoo. e.g.: lions, elephants, and zebras.
On the other hand, "for example" should not be used instead of "i.e.", since that has a different meaning. If you want to cover that, too, this should do:
- "that is", "that means", "in other words", or "namely", not "i.e."
Sorry, don't have any good examples for that. Should it be used at all?
Actual result
The suggested usage of "for example" instead of "i.e." is bad advice, because it would change the meaning of the sentence. In fact, the current example of using "i.e." does not make much sense, unless the only animals that the zoo contains are lions, elephants, and zebras – not sure if that qualifies as "many animals" though.
- "for example", not "i.e."
✅ There are many animals in the zoo. For example: lions, elephants, and zebras.
⛔️ There are many animals in the zoo, for example: lions, elephants, and zebras.
⛔️ There are many animals in the zoo. i.e.: lions, elephants, and zebras.
Steps to reproduce
Read the guide.
Troubleshooting
Until this is fixed, one might simply ignore the guide, and just make sure that both "i.e." and "e.g." are expressed in English language.
Description
As decided by the SIG Content, the ASCII header needs to be removed from the chart_README.md
template.
Apart from the template, it must to be removed from all existing chart README.md
documents in the kyma
repository.
Confirm these statements before you submit the issue:
Description
The guideline on CRDs (guidelines/custom-resource-definitions.md) is using "kyma.cx" as domain for kyma-specific CRDs. That should be changed to "kyma-project.io".
Description
As it was agreed at the SIG content meeting, the attached material for the Kyma open-source branded template needs to be placed in the community repository (perhaps a separate folder under templates?) so it could be used to introduce the Kyma open-source project.
Attachments include:
assets
folderDescription
Update release-subscription.md
to include the GitHub's new feature to only subscribe for watching releases.
Confirm these statements before you submit the issue:
Description
Reasons
Every documentation topic must follow https://github.com/kyma-project/community/blob/master/guidelines/content-guidelines/content-strategy.md#documentation-types and all those types must have templates which make it much easier for anybody to contribute content
Confirm these statements before you submit the issue:
Description
Reasons
We recently agreed to have some exception rule for allowing screen shots. We need to provide guidelines for that
Description
Reasons
We need clear decision on how we generate change log for our projects that are released
Description
Update the content-strategy.md
document with the new numbering format.
Update existing templates for official docs and remove information document types from the document names as the number of the doc already describes the type and the metadata in the doc also provides these details.
Add formatting to the names of the {xxx}
CustomResourceDefinitions (CRD) in the related template.
Description
Reasons
Consistency in the repository settings throughout the organization. You need to know not only what structure the repo should get but also what settings are required.
Confirm these statements before you submit the issue:
Description
security/{score}
)Reasons
Description
Note that:
Reasons
Created on 2018-11-29 by Paweł Kosiec (@pkosiec).
Name | Description |
---|---|
Title | UI API Layer Modularization |
Ultimate decision maker(s) | Kyma Council |
Due date | 2018-11-30 |
Input provider(s) | UI API Layer main contributors, Product Owners |
Group(s) affected by the decision | Kyma Developers |
Decision type | Choice |
Earliest date to revisit the decision | 2019-02-28 |
Affected decisions |
UI API Layer exposes GraphQL API for the Kyma Console. It consists of resolver logic for different domains, like Kubernetes, Service Catalog, Remote Environments, Kubeless, etc. As Kyma needs to be modularized, users should be able to install only the components they need.
The current approach we use in UI API Layer makes it impossible. During the GraphQL server start, we try to synchronize Stores of all Informers. As a result, if a resource of a specific type doesn't exist, UI API Layer won't start properly because its Informer will return an error.
The decision is to implement UI API Layer module pluggability according to the proposal merged in #141, which bases on replacing UI API Layer resolver logic implementation depending on Back-end Module Custom Resource existence.
Proposed on 2018-11-29.
Accepted on 2018-12-03.
This decision have the following consequences:
Description
Update the Tool section in the diagram guidelines to mention that it is enough to add SVG
diagram format to the relevant assets
folder without html
or xml
source since you can edit SVG
directly in draw.io.
Reasons
You can edit SVG
directly in draw.io so there is no need to add the source to the assets
folder as well.
Confirm these statements before you submit the issue:
Description
Reasons
be consistent across all documentation topic and document Custom Resources the same way everywhere
Hi,
We need customized GitHub analytics for the Kyma project.
These analytics should include the following KPIs:
These data should be filtered by period. Analytics should have a summary dashboard covering main KPIs listed above in the form of numbers. Also, we need a detail view of each KPI in a form of numbers and graphs.
A reference for the GitHub analytics is the Google analytics.
I hope this was detailed enough for you to work on a script. Let me know if you need more input from my side.
Best,
Ana
Description
Describe the decision making process based on the decision log.
Reasons
Describe the consistent decision making process applicable for the whole Kyma community
Description
As confirmed, the Creative Commons (CC) license is not required additionally in the repositories, Apache license is sufficient.
This as part of the clean-up, update the following:
repository-template
README.md
- pls remove this information.community
repo.docs
folders in all repositories in the kyma
organization and make sure only Apache license is present at the root of all repositories.Created on 2018-10-12 by Mateusz Szostok (@mszostok)
Name | Description |
---|---|
Title | Extracting common libraries used in Kyma projects to one place. |
Ultimate decision maker(s) | Kyma Council |
Due date | 2018-11-30 |
Input provider(s) | SIG Core, Kyma Developers |
Group(s) affected by the decision | Kyma Developers |
Decision type | Binary |
Earliest date to revisit the decision | 2018-01-27 |
Affected decisions |
Kyma project was consolidated and now all core project written in Go are placed in one repository. Unfortunately, still all projects are written in a different way.
This situation causes the following problems:
The decision is to extract common code from Kyma components to the common package and use it in all required places. Thanks to that Kyma Developers can use in Kyma projects unified and well tested libraries which will be easier to understand and make a future development faster.
Proposed on 2018-10-17.
Accepted on 2018-11-30.
Once approved, these are the consequences:
Description
If you add a new component to the kyma/docs, the following files must be changed:
Reasons
As there are quite a few steps to complete when adding a new component to the kyma/docs folder, create a document describing this process step by step. This would leave contributors no room for doubts when adding a new component to docs.
Please add an information to the decision log template regarding the possibility to revisit particular decision earlier if needed. In that case a ticket would need to be created.
Description
Since CI does no longer run automatically on the PRs, it is required to run the builds manually before the PR is merged.
Update these CONTRIBUTING.md documents with the manual CI run step information:
Description
Add information to the Links section in the guidelines that in the docs
inside the kyma
repository we should cross-reference only external docs and if we want to make a reference to any other related docs from the docs
directory, we should reference it by a (bolded) name only.
Reasons
The internal cross-references do not work on the Console and on the website.
Description
Add information about meeting recordings and mailing list in templates
https://github.com/kyma-project/community/tree/master/guidelines/templates/resources
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.