github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-24 09:48:58 -04:00
Code Issues Projects Releases Packages Wiki Activity

Some updates to our dev docs (#120981)

Browse source 
* Master -> main update branching strategy with make it minor

* Follow the new dev docs process and keep nav inside this repo

* add back nav links that are in a different repo

Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
Stacey Gammon 2021-12-13 11:47:03 -05:00 • committed by GitHub
parent 9b5efb2733
commit 6c4c5e1299
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 186 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

2
dev_docs/api_welcome.mdx
View file

@ -44,7 +44,7 @@ This documentation is being automatically generated using an
There is one extra step required to have your API docs show up in the _navigation_ of the docs system. Follow
the instructions <DocLink id="docsSetup" section="configure-the-nav-for-your-content" text="here" /> to learn how to
configure the navigation menu. The nav file you need to
edit is: [https://github.com/elastic/elastic-docs/blob/master/config/nav-kibana-dev.ts](https://github.com/elastic/elastic-docs/blob/master/config/nav-kibana-dev.ts)
edit is: [https://github.com/elastic/elastic-docs/blob/main/config/nav-kibana-dev.ts](https://github.com/elastic/elastic-docs/blob/main/config/nav-kibana-dev.ts)
Your API docs will exist in the top level [`api_docs` folder](https://github.com/elastic/kibana/tree/main/api_docs) and will use a doc id of the pattern `kib${PluginName}PluginApi`.

9
dev_docs/contributing/best_practices.mdx
View file

@ -141,6 +141,9 @@ export type foo: string | AnInterface;
Running Kibana with `yarn start --run-examples` will include all [example plugins](https://github.com/elastic/kibana/tree/main/examples). These are tested examples of platform services in use. We strongly encourage anyone providing a platform level service or <DocLink id="kibBuildingBlocks" text="building block"/> to include a tutorial that links to a tested example plugin. This is better than relying on copied code snippets, which can quickly get out of date.
You can also visit these [examples plugins hosted online](https://demo.kibana.dev/8.0/app/home). Note that because anonymous access is enabled, some
of the demos are currently not working.
## Performance
Build with scalability in mind.
@ -150,6 +153,8 @@ Build with scalability in mind.
- Consider large data sets, that span a long time range
- Consider slow internet and low bandwidth environments
<DocLink id="kibDevPerformance" text="Read more about performance."/>
## Accessibility
Did you know Kibana makes a public statement about our commitment to creating an accessible product for people
@ -202,13 +207,13 @@ Kibana code base, try not to contribute to this volatility. Doing this can:
All of the above contributes to more bugs being found in the QA cycle and can cause a delay in the release. Prefer instead to merge
your large change right _after_ feature freeze. If you are worried about missing your initial release version goals, review our
[release train philophy](https://github.com/elastic/dev/blob/master/shared/time-based-releases.md). It's okay!
<DocLink id="devTimeBasedReleases" text="release train philosophy"/>. It's okay!
</DocCallOut>
### Size
When possible, build features with incrementals sets of small and focused PRs, but don't check in unused code, and don't expose any feature on master that you would not be comfortable releasing.
When possible, build features with incremental sets of small and focused PRs, but don't check in unused code, and don't expose any feature on main that you would not be comfortable releasing.
![product_stages](../assets/product_stages.png)

2
dev_docs/contributing/code_walkthrough.mdx
View file

@ -21,7 +21,7 @@ Managed by the operations team to contain Jenkins settings. Can be ignored by fo
## [.github](https://github.com/elastic/kibana/tree/main/.github)
Contains GitHub configuration settings. This file contains issue templates, and the [CODEOWNERS](https://github.com/elastic/kibana/blob/main/.github/CODEOWNERS) file. It's important for teams to keep the CODEOWNERS file up-to-date so the right team is pinged for a code owner review on PRs that edit certain files. Note that the `CODEOWNERS` file only exists on the main/master branch, and is not backported to other branches in the repo.
Contains GitHub configuration settings. This file contains issue templates, and the [CODEOWNERS](https://github.com/elastic/kibana/blob/main/.github/CODEOWNERS) file. It's important for teams to keep the CODEOWNERS file up-to-date so the right team is pinged for a code owner review on PRs that edit certain files. Note that the `CODEOWNERS` file only exists on the main branch, and is not backported to other branches in the repo.
## [api_docs](https://github.com/elastic/kibana/tree/main/api_docs)

26
dev_docs/contributing/how_we_use_github.mdx
View file

@ -15,16 +15,14 @@ We follow the [GitHub forking model](https://help.github.com/articles/fork-a-rep
At Elastic, all products in the stack, including Kibana, are released at the same time with the same version number. Most of these projects have the following branching strategy:
- master is the next major version.
- `<major>.x` is the next minor version.
- `<major>.<minor>` is the next release of a minor version, including patch releases.
- `main` points to the next minor version.
- `<major>.<minor>` is the previously released minor version, including patch releases.
As an example, let’s assume that the 7.x branch is currently a not-yet-released 7.6.0. Once 7.6.0 has reached feature freeze, it will be branched to 7.6 and 7.x will be updated to reflect 7.7.0. The release of 7.6.0 and subsequent patch releases will be cut from the 7.6 branch. At any time, you can verify the current version of a branch by inspecting the version attribute in the package.json file within the Kibana source.
As an example, let’s assume that the main branch is currently a not-yet-released 8.1.0. Once 8.1.0 has reached feature freeze, it will be branched to 8.1 and main will be updated to reflect 8.2.0. The release of 8.1.0 and subsequent patch releases will be cut from the 8.1 branch. At any time, you can verify the current version of a branch by inspecting the version attribute in the package.json file within the Kibana source.
Pull requests are made into the master branch and then backported when it is safe and appropriate.
Pull requests are made into the main branch and only backported when it is safe and appropriate.
- Breaking changes do not get backported and only go into master.
- All non-breaking changes can be backported to the `<major>.x` branch.
- Breaking changes can _only_ be made to `main` if there has been at least an 18 month deprecation period _and_ the breaking change has been approved. Telemetry showing current usage is crucial for gaining approval.
- Features should not be backported to a `<major>.<minor>` branch.
- Bug fixes can be backported to a `<major>.<minor>` branch if the changes are safe and appropriate. Safety is a judgment call you make based on factors like the bug’s severity, test coverage, confidence in the changes, etc. Your reasoning should be included in the pull request description.
- Documentation changes can be backported to any branch at any time.
@ -63,26 +61,26 @@ In order to assist with developer tooling we ask that all Elastic engineers use
Rebasing can be tricky, and fixing merge conflicts can be even trickier because it involves force pushing. This is all compounded by the fact that attempting to push a rebased branch remotely will be rejected by git, and you’ll be prompted to do a pull, which is not at all what you should do (this will really mess up your branch’s history).
Here’s how you should rebase master onto your branch, and how to fix merge conflicts when they arise.
Here’s how you should rebase main onto your branch, and how to fix merge conflicts when they arise.
First, make sure master is up-to-date.
First, make sure main is up-to-date.
```bash
git checkout master
git checkout main
git fetch upstream
git rebase upstream/master
git rebase upstream/main
```
Then, check out your branch and rebase master on top of it, which will apply all of the new commits on master to your branch, and then apply all of your branch’s new commits after that.
Then, check out your branch and rebase main on top of it, which will apply all of the new commits on main to your branch, and then apply all of your branch’s new commits after that.
```bash
git checkout name-of-your-branch
git rebase master
git rebase main
```
You want to make sure there are no merge conflicts. If there are merge conflicts, git will pause the rebase and allow you to fix the conflicts before continuing.
You can use git status to see which files contain conflicts. They’ll be the ones that aren’t staged for commit. Open those files, and look for where git has marked the conflicts. Resolve the conflicts so that the changes you want to make to the code have been incorporated in a way that doesn’t destroy work that’s been done in master. Refer to master’s commit history on GitHub if you need to gain a better understanding of how code is conflicting and how best to resolve it.
You can use git status to see which files contain conflicts. They’ll be the ones that aren’t staged for commit. Open those files, and look for where git has marked the conflicts. Resolve the conflicts so that the changes you want to make to the code have been incorporated in a way that doesn’t destroy work that’s been done in main. Refer to main commit history on GitHub if you need to gain a better understanding of how code is conflicting and how best to resolve it.
Once you’ve resolved all of the merge conflicts, use git add -A to stage them to be committed, and then use git rebase --continue to tell git to continue the rebase.

4
dev_docs/tutorials/submit_a_pull_request.mdx
View file

@ -23,7 +23,7 @@ After cloning your fork and navigating to the directory containing your fork:
```bash
# Make sure you currently have the branch checked out off of which you'd like to work
git checkout master
git checkout main
# Create a new branch
git checkout -b fix-typos-in-readme
@ -76,7 +76,7 @@ See [Pull request review guidelines](https://www.elastic.co/guide/en/kibana/mast
## Updating your PR with upstream
If your pull request hasn't been updated with the latest code from the upstream/target branch, e.g. `master`, in the last 48 hours, it won't be able to merge until it is updated. This is to help prevent problems that could occur by merging stale code into upstream, e.g. something new was recently merged that is incompatible with something in your pull request.
If your pull request hasn't been updated with the latest code from the upstream/target branch, e.g. `main`, in the last 48 hours, it won't be able to merge until it is updated. This is to help prevent problems that could occur by merging stale code into upstream, e.g. something new was recently merged that is incompatible with something in your pull request.
As an alternative to using `git` to manually update your branch, you can leave a comment on your pull request with the text `@elasticmachine merge upstream`. This will automatically update your branch and kick off CI for it.

160
nav-kibana-dev.docnav.json Normal file
View file

@ -0,0 +1,160 @@
{
"mission": "Kibana Developer Guide",
"id": "kibDevDocs",
"landingPageId": "kibDevDocsWelcome",
"icon": "logoKibana",
"description": "Developer documentation for building custom Kibana plugins and extending Kibana functionality.",
"items": [
{
"category": "Getting started",
"items": [
{ "id": "kibDevDocsWelcome" },
{ "id": "kibDevTutorialSetupDevEnv" },
{ "id": "kibHelloWorldApp" },
{ "id": "kibDevAddData" },
{ "id": "kibTroubleshooting" }
]
},
{
"category": "Key concepts",
"items": [
{ "id": "kibPlatformIntro" },
{ "id": "kibDevAnatomyOfAPlugin" },
{ "id": "kibDevPerformance" },
{ "id": "kibBuildingBlocks" },
{ "id": "kibDevDocsSavedObjectsIntro", "label": "Saved objects" },
{ "id": "kibDevDocsPersistableStateIntro" },
{ "id": "kibDataPlugin", "label": "Data" },
{ "id": "kibCoreLogging" },
{ "id": "kibUsageCollectionPlugin" },
{ "id": "kibDataViewsKeyConcepts" },
{ "id": "kibDevKeyConceptsNavigation" }
]
},
{
"category": "Tutorials",
"items": [
{ "id": "kibDevTutorialTestingPlugins" },
{ "id": "kibDevTutorialSavedObject" },
{ "id": "kibDevTutorialSubmitPullRequest" },
{ "id": "kibDevTutorialExpressions" },
{ "id": "kibDevDocsKPTTutorial" },
{ "id": "kibDevTutorialDataSearchAndSessions", "label": "data.search" },
{ "id": "kibDevTutorialDataViews" },
{ "id": "kibDevTutorialDebugging" },
{
"id": "kibDevTutorialBuildingDistributable",
"label": "Building a Kibana distributable"
},
{ "id": "kibDevTutorialServerEndpoint" }
]
},
{
"category": "Contributing",
"items": [
{ "id": "kibRepoStructure" },
{ "id": "kibDevPrinciples" },
{ "id": "kibStandards" },
{ "id": "ktRFCProcess" },
{ "id": "kibBestPractices" },
{ "id": "kibStyleGuide" },
{ "id": "kibGitHub" }
]
},
{
"category": "Contributors Newsletters",
"items": [
{ "id": "kibNovember2021ContributorNewsletter" },
{ "id": "kibOctober2021ContributorNewsletter" },
{ "id": "kibSeptember2021ContributorNewsletter" },
{ "id": "kibAugust2021ContributorNewsletter" },
{ "id": "kibJuly2021ContributorNewsletter" },
{ "id": "kibJune2021ContributorNewsletter" },
{ "id": "kibMay2021ContributorNewsletter" },
{ "id": "kibApril2021ContributorNewsletter" },
{ "id": "kibMarch2021ContributorNewsletter" }
]
},
{
"category": "API documentation",
"items": [
{ "id": "kibDevDocsApiWelcome" },
{ "id": "kibDevDocsPluginDirectory" },
{ "id": "kibDevDocsDeprecationsByPlugin" },
{ "id": "kibDevDocsDeprecationsByApi" },
{ "id": "kibCorePluginApi" },
{ "id": "kibCoreApplicationPluginApi" },
{ "id": "kibCoreChromePluginApi" },
{ "id": "kibCoreHttpPluginApi" },
{ "id": "kibCoreSavedObjectsPluginApi" },
{ "id": "kibFieldFormatsPluginApi" },
{ "id": "kibDataPluginApi" },
{ "id": "kibDataAutocompletePluginApi" },
{ "id": "kibDataEnhancedPluginApi" },
{ "id": "kibDataViewsPluginApi" },
{ "id": "kibDataQueryPluginApi" },
{ "id": "kibDataSearchPluginApi" },
{ "id": "kibDataUiPluginApi" },
{ "id": "kibBfetchPluginApi" },
{ "id": "kibAlertingPluginApi" },
{ "id": "kibTaskManagerPluginApi" },
{ "id": "kibActionsPluginApi" },
{ "id": "kibEventLogPluginApi" },
{ "id": "kibTriggersActionsUiPluginApi" },
{ "id": "kibCasesPluginApi" },
{ "id": "kibChartsPluginApi" },
{ "id": "kibDashboardPluginApi" },
{ "id": "kibDevToolsPluginApi" },
{ "id": "kibDiscoverPluginApi" },
{ "id": "kibEmbeddablePluginApi" },
{ "id": "kibEncryptedSavedObjectsPluginApi" },
{ "id": "kibEnterpriseSearchPluginApi" },
{ "id": "kibEsUiSharedPluginApi" },
{ "id": "kibExpressionsPluginApi" },
{ "id": "kibFeaturesPluginApi" },
{ "id": "kibFileUploadPluginApi" },
{ "id": "kibFleetPluginApi" },
{ "id": "kibGlobalSearchPluginApi" },
{ "id": "kibHomePluginApi" },
{ "id": "kibInspectorPluginApi" },
{ "id": "kibKibanaReactPluginApi" },
{ "id": "kibKibanaUtilsPluginApi" },
{ "id": "kibLensPluginApi" },
{ "id": "kibLicenseManagementPluginApi" },
{ "id": "kibLicensingPluginApi" },
{ "id": "kibListsPluginApi" },
{ "id": "kibManagementPluginApi" },
{ "id": "kibMapsPluginApi" },
{ "id": "kibMlPluginApi" },
{ "id": "kibMonitoringPluginApi" },
{ "id": "kibNavigationPluginApi" },
{ "id": "kibNewsfeedPluginApi" },
{ "id": "kibObservabilityPluginApi" },
{ "id": "kibRemoteClustersPluginApi" },
{ "id": "kibReportingPluginApi" },
{ "id": "kibRollupPluginApi" },
{ "id": "kibRuntimeFieldsPluginApi" },
{ "id": "kibSavedObjectsManagementPluginApi" },
{ "id": "kibSavedObjectsTaggingOssPluginApi" },
{ "id": "kibSavedObjectsTaggingPluginApi" },
{ "id": "kibSavedObjectsPluginApi" },
{ "id": "kibSecuritySolutionPluginApi" },
{ "id": "kibSecurityPluginApi" },
{ "id": "kibSharePluginApi" },
{ "id": "kibSnapshotRestorePluginApi" },
{ "id": "kibSpacesPluginApi" },
{ "id": "kibStackAlertsPluginApi" },
{ "id": "kibTelemetryCollectionManagerPluginApi" },
{ "id": "kibTelemetryCollectionXpackPluginApi" },
{ "id": "kibTelemetryManagementSectionPluginApi" },
{ "id": "kibTelemetryPluginApi" },
{ "id": "kibUiActionsEnhancedPluginApi" },
{ "id": "kibUiActionsPluginApi" },
{ "id": "kibUrlForwardingPluginApi" },
{ "id": "kibUsageCollectionPluginApi" },
{ "id": "kibVisTypeTimeseriesPluginApi" },
{ "id": "kibVisualizationsPluginApi" }
]
}
]
}

3
src/dev/precommit_hook/casing_check_config.js
View file

@ -42,6 +42,9 @@ export const IGNORE_FILE_GLOBS = [
'test/package/Vagrantfile',
'**/test/**/fixtures/**/*',
// Required to match the name in the docs.elastic.dev repo.
'nav-kibana-dev.docnav.json',
// filename must match language code which requires capital letters
'**/translations/*.json',