mirror of
https://github.com/fleetdm/fleet
synced 2026-05-22 16:39:01 +00:00
Engineering README.md housekeeping (#7031)
This commit is contained in:
Mike Thomas
GitHub
parent
5aa265bc30
commit
e280c04c94
2 changed files with 403 additions and 305 deletions
|
|
@ -5,7 +5,7 @@ contributors.
|
|||
|
||||
## Communities
|
||||
|
||||
Fleet's users and broader audience are spread across many online platforms. Here are the most active communities where Fleet's developer relations and social media team members participate at least once every weekday:
|
||||
Fleet's users and broader audience are spread across many online platforms. Here are the most active communities where Fleet's developer relations and social media team members participate at least once every weekday:
|
||||
|
||||
- [Osquery Slack](https://join.slack.com/t/osquery/shared_invite/zt-h29zm0gk-s2DBtGUTW4CFel0f0IjTEw) (`#fleet` channel)
|
||||
- [MacAdmins Slack](https://www.macadmins.org/) (`#fleet` channel)
|
||||
|
|
@ -16,7 +16,8 @@ Fleet's users and broader audience are spread across many online platforms. Her
|
|||
- [r/sysadmin Discord](https://discord.gg/sysadmin)
|
||||
|
||||
### Goals
|
||||
Our primary quality objectives are *customer service* and *defect reduction*. We try to optimize the following:
|
||||
|
||||
Our primary quality objectives are _customer service_ and _defect reduction_. We try to optimize the following:
|
||||
|
||||
- Customer response time
|
||||
- The number of bugs resolved per release cycle
|
||||
|
|
@ -34,7 +35,7 @@ Our primary quality objectives are *customer service* and *defect reduction*. We
|
|||
|
||||
### Requesting more details
|
||||
|
||||
Typically, the *questions*, *bug reports*, and *feature requests* raised by community members will be missing helpful context, recreation steps, or motivations.
|
||||
Typically, the _questions_, _bug reports_, and _feature requests_ raised by community members will be missing helpful context, recreation steps, or motivations.
|
||||
|
||||
❓ For questions that you don't immediately know the answer to, it's helpful to ask follow-up questions to receive additional context.
|
||||
|
||||
|
|
@ -90,231 +91,19 @@ There are several locations in Fleet's public and internal documentation that ca
|
|||
|
||||
Community team members can reach the engineering oncall for assistance by writing a message with `@oncall` in the `#help-engineering` channel of the Fleet Slack.
|
||||
|
||||
## Fleet docs
|
||||
|
||||
### How to request a review for Markdown changes to the docs
|
||||
|
||||
When creating a pull request for Markdown changes in the docs, request a review from Desmi Dizney, who will do an editor pass, and then hand over the review to the [on-call engineer](https://fleetdm.com/handbook/engineering#oncall-rotation) if necessary.
|
||||
|
||||
### Markdown
|
||||
Fleet's documentation and handbook are written in [Markdown](https://about.gitlab.com/handbook/markdown-guide/). Using Markdown lets us keep our documentation consistently formatted and viewable directly from the Fleet GitHub repo. The Markdown files in the `/docs` and `/handbook` folders are converted to HTML for the Fleet website.
|
||||
|
||||
When making changes to the Fleet docs or handbook, there are a few differences in how the Markdown will render on GitHub and the Fleet website.
|
||||
|
||||
#### Linebreaks and newlines
|
||||
Any time you need to add a line break in Markdown, you should add a new line. It is vital to make sure paragraphs are separated by new lines. Otherwise, they will render as the same HTML element.
|
||||
|
||||
For example, if you were adding this section to the docs:
|
||||
|
||||
```
|
||||
line one
|
||||
line two
|
||||
```
|
||||
|
||||
The Markdown would render on the Fleet website as
|
||||
|
||||
line one
|
||||
line two
|
||||
|
||||
To make sure formatting is consistent across GitHub and the Fleet website, you need to add a new line anywhere you want a line break. For example, if we separate the lines with a new line:
|
||||
|
||||
```
|
||||
line one
|
||||
|
||||
line two
|
||||
```
|
||||
|
||||
|
||||
The Markdown will render correctly as
|
||||
|
||||
line one
|
||||
|
||||
line two
|
||||
|
||||
#### Ordered lists
|
||||
|
||||
Content nested within an ordered list needs to be indented. If the list is not formatted correctly, the number will reset on each list item.
|
||||
|
||||
For example, this list:
|
||||
|
||||
```
|
||||
1. Item one
|
||||
|
||||
Paragraph about item one
|
||||
|
||||
2. Item two
|
||||
```
|
||||
|
||||
On the Fleet website, this ordered list would be rendered as
|
||||
|
||||
1. Item one
|
||||
|
||||
Paragraph about item one
|
||||
|
||||
2. Item two
|
||||
|
||||
To make sure that ordered lists increment on the Fleet website, you can indent the content nested within the list. For example, the same ordered list with indentation:
|
||||
|
||||
```
|
||||
1. Item one
|
||||
|
||||
Paragraph about item one
|
||||
|
||||
2. Item two
|
||||
```
|
||||
|
||||
This ordered list will render correctly as
|
||||
|
||||
1. Item one
|
||||
|
||||
Paragraph about item one
|
||||
|
||||
2. Item two
|
||||
|
||||
### Docs style guide
|
||||
|
||||
#### Headings
|
||||
|
||||
Headings help readers quickly scan content to find what they need. Organize page content using clear headings specific to the topic they describe.
|
||||
|
||||
Keep headings brief, organized, and in a logical order:
|
||||
|
||||
* H1: Page title
|
||||
* H2: Main headings
|
||||
* H3: Subheadings
|
||||
* H4: Sub-subheadings (headings nested under subheadings)
|
||||
|
||||
Try to stay within three or four heading levels. Complicated documents may use more, but pages with a simpler structure are easier to read.
|
||||
|
||||
### SQL statements
|
||||
|
||||
When adding SQL statements, all SQL reserved words should be uppercase, and all identifiers (such as tables and columns) should be lowercase. Here is an example:
|
||||
|
||||
```sql
|
||||
SELECT days, hours, total_seconds FROM uptime;
|
||||
```
|
||||
|
||||
### Adding a link to the Fleet docs
|
||||
|
||||
You can link documentation pages to each other using relative paths. For example, in `docs/Using-Fleet/Fleet-UI.md`, you can link to `docs/Using-Fleet/Permissions.md` by writing `[permissions](./Permissions.md)`. This will automatically be transformed into the appropriate URL for `fleetdm.com/docs`.
|
||||
|
||||
However, the `fleetdm.com/docs` compilation process does not account for relative links to directories **outside** of `/docs`.
|
||||
This is why it’s essential to follow the file path exactly when adding a link to Fleet docs.
|
||||
When directly linking to a specific section, always format the spaces within a section name to use a hyphen instead of an underscore. For example, when linking to the `osquery_result_log_plugin` section of the configuration reference docs, use a relative link like the following: `./Configuration.md#osquery-result-log-plugin`.
|
||||
|
||||
### Linking to a location on GitHub
|
||||
When adding a link to a location on GitHub outside of `/docs`, be sure to use the canonical form of the URL.
|
||||
|
||||
Navigate to the file's location on GitHub, and press "y" to transform the URL into its canonical form.
|
||||
|
||||
### How to fix a broken link
|
||||
For instances when a broken link is discovered on fleetdm.com, always check if the link is a relative link to a directory outside of `/docs`.
|
||||
|
||||
An example of a link that lives outside of `/docs` is:
|
||||
|
||||
```
|
||||
../../tools/app/prometheus
|
||||
```
|
||||
|
||||
If the link lives outside `/docs`, head to the file's location on GitHub (in this case, [https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)](https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)), and press "y" to transform the URL into its canonical form (a version of the link that will always point to the same version of the file) ([https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml](https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml)). Replace the relative link with this link in the Markdown file.
|
||||
|
||||
> Note that the instructions above also apply to adding links in the Fleet handbook.
|
||||
|
||||
### Ordering a page in the Fleet docs
|
||||
The order we display documentation pages on fleetdm.com is determined by `pageOrderInSection` meta tags. These pages are sorted in their respective sections in **ascending** order by the `pageOrderInSection` value. Every Markdown file (except readme and faq pages) in the `docs/` folder must have a meta tag with a positive 'pageOrderInSection' value.
|
||||
|
||||
|
||||
We leave large gaps between values to make future changes easier. For example, the first page in the "Using Fleet" section of the docs has a `pageOrderInSection` value of 100, and the next page has a value of 200. The significant difference between values allows us to add, remove and reorder pages without changing the value of multiple pages at a time.
|
||||
|
||||
When adding or reordering a page, try to leave as much room between values as possible. If you were adding a new page that would go between the two pages from the example above, you would add `<meta name="pageOrderInSection" value="150">` to the page.
|
||||
|
||||
### Adding an image to the Fleet docs
|
||||
Try to keep images in the docs at a minimum. Images can be a quick way to help users understand a concept or direct them towards a specific user interface(UI) element. Still, too many can make the documentation feel cluttered and more difficult to maintain.
|
||||
|
||||
When adding images to the Fleet documentation, follow these guidelines:
|
||||
- UI screenshots should be a 4:3 aspect ratio (1280x960). This is an optimal size for the container width of the docs and ensures that content in screenshots is as clear as possible to view in the docs (and especially on mobile devices).
|
||||
- You can set up a custom preset in the Google Chrome device toolbar (in Developer Tools) to quickly adjust your browser to the correct size for taking a screenshot.
|
||||
- Keep the images as simple as possible to maintain. Screenshots can get out of date quickly as UIs change.
|
||||
- Exclude unnecessary images. Images should be used to help emphasize information in the docs, not replace it.
|
||||
- Minimize images per doc page. For doc maintainers and users, more than one or two per page can get overwhelming.
|
||||
- The goal is for the docs to look good on every form factor, from 320px window width all the way up to infinity. Full window screenshots and images with too much padding on the sides will be less than the width of the user's screen. When adding a large image, make sure it is easily readable at all widths.
|
||||
|
||||
Images can be added to the docs using the Markdown image link format, e.g., ``
|
||||
The images used in the docs live in `docs/images/`. Note that you must provide the URL of the image in the Fleet GitHub repo for it to display properly on both GitHub and the Fleet website.
|
||||
|
||||
> Note that the instructions above also apply to adding images in the Fleet handbook.
|
||||
|
||||
### Adding a video to the Fleet docs
|
||||
|
||||
You can embed a video at the top of a doc page. The video must be uploaded to YouTube first. Using the standard YouTube embed code causes issues on mobile. So, we wrote our own code to make sure the video fits every screen size.
|
||||
|
||||
Copy and paste this code where you want to embed the video in the doc.
|
||||
|
||||
```
|
||||
<div purpose=”embedded-content”>
|
||||
<iframe class="video" src="YOUTUBE EMBED URL GOES HERE" allowfullscreen></iframe>
|
||||
</div>
|
||||
```
|
||||
|
||||
You’ll notice a section to enter the YouTube embed URL. Here’s how to find it:
|
||||
|
||||
1. Open the YouTube video in your browser.
|
||||
2. Click **Share** (located below the title).
|
||||
3. Select the **Embed** option.
|
||||
4. Copy the URL from the embed code.
|
||||
|
||||
You’ll know you have the right URL if you see “embed” after the domain.
|
||||
|
||||
Paste the YouTube embed URL in the code we provided.
|
||||
|
||||
|
||||
|
||||
### Adding a mermaid diagram to the Fleet Docs
|
||||
|
||||
The Fleet Docs support diagrams that are written in mermaid.js syntax. Take a look at the [Mermaid docs](https://mermaid-js.github.io/mermaid/#/README) to learn about the syntax language and what types of diagrams you can display.
|
||||
|
||||
To add a mermaid diagram to the docs, you need to add a code block and specify that it is written in the mermaid language by adding `mermaid` to the opening backticks (i.e., ` ```mermaid`).
|
||||
|
||||
For example, the following code block is a mermaid diagram that has **not** been specified as a mermaid code block:
|
||||
|
||||
```
|
||||
graph TD;
|
||||
A-->D
|
||||
B-->D
|
||||
C-->D
|
||||
D-->E
|
||||
```
|
||||
Once we specify the `mermaid` as the language in the code block, it will render as a mermaid diagram on fleetdm.com and GitHub.
|
||||
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->D
|
||||
B-->D
|
||||
C-->D
|
||||
D-->E
|
||||
```
|
||||
|
||||
If the mermaid syntax is incorrect, the diagram will be replaced with an image displaying an error, as shown in the following example where the code block was written with **intentional** syntax errors:
|
||||
|
||||
```mermaid
|
||||
graph TD;
|
||||
A--D
|
||||
```
|
||||
|
||||
## Pull requests
|
||||
|
||||
The most important thing when community members contribute to Fleet is to show them we value their time and effort. We need to get eyes on community pull requests quickly (within one business day) and get them merged or give feedback as soon as we can.
|
||||
|
||||
### Process for managing community contributions
|
||||
|
||||
The Community Engagement DRI is responsible for keeping an eye out for new community contributions, getting them merged if possible, and getting the right eyes on them if they require a review.
|
||||
The Community Engagement DRI is responsible for keeping an eye out for new community contributions, getting them merged if possible, and getting the right eyes on them if they require a review.
|
||||
|
||||
Each business day, the Community Engagement DRI will check open pull requests to
|
||||
|
||||
1. check for new pull requests (PRs) from the Fleet community.
|
||||
1. check for new pull requests (PRs) from the Fleet community.
|
||||
2. approve and merge any community PRs that are ready to go.
|
||||
3. make sure there aren't any existing community PRs waiting for a follow-up from Fleet.
|
||||
|
||||
3. make sure there aren't any existing community PRs waiting for a follow-up from Fleet.
|
||||
|
||||
#### Identify community contributions
|
||||
|
||||
|
|
@ -323,23 +112,26 @@ When a new pull request is submitted by a community contributor (someone not a m
|
|||
- Add the `:community` label.
|
||||
- Self-assign for review.
|
||||
- Check whether the PR can be merged or needs to be reviewed by the Product team.
|
||||
- Things that generally don't need additional review:
|
||||
- Minor changes to the docs.
|
||||
- Small bug fixes.
|
||||
|
||||
- Additions or fixes to the Standard Query Library (as long as the SQL works properly and is attributed correctly).
|
||||
- If a review is needed:
|
||||
- Request a review from the [Product DRI](../people/README.md#directly-responsible-individuals). They should approve extensive changes and new features. Ask in the #g-product channel in Fleet's Slack for more information.
|
||||
- Tag the DRI and the contributor in a comment on the PR, letting everyone know why an additional review is needed. Make sure to say thanks!
|
||||
- Find any related open issues and make a note in the comments.
|
||||
- Things that generally don't need additional review:
|
||||
|
||||
> Please refer to our [PRs from the community](https://docs.google.com/document/d/13r0vEhs9LOBdxWQWdZ8n5Ff9cyB3hQkTjI5OhcrHjVo/edit?usp=sharing) guide and use your best judgment.
|
||||
- Minor changes to the docs.
|
||||
- Small bug fixes.
|
||||
|
||||
- Additions or fixes to the Standard Query Library (as long as the SQL works properly and is attributed correctly).
|
||||
|
||||
- If a review is needed:
|
||||
- Request a review from the [Product DRI](../people/README.md#directly-responsible-individuals). They should approve extensive changes and new features. Ask in the #g-product channel in Fleet's Slack for more information.
|
||||
- Tag the DRI and the contributor in a comment on the PR, letting everyone know why an additional review is needed. Make sure to say thanks!
|
||||
- Find any related open issues and make a note in the comments.
|
||||
|
||||
> Please refer to our [PRs from the community](https://docs.google.com/document/d/13r0vEhs9LOBdxWQWdZ8n5Ff9cyB3hQkTjI5OhcrHjVo/edit?usp=sharing) guide and use your best judgment.
|
||||
|
||||
#### Communicate with contributors
|
||||
|
||||
Community contributions are fantastic, and it's important that the contributor knows how much they are appreciated. The best way to do that is to keep in touch while we're working on getting their PR approved.
|
||||
|
||||
While each team member is responsible for monitoring their active issues and pull requests, the Community Engagement DRI will check in on pull requests with the `:community ` label daily to make sure everything is moving along. If there's a comment or question from the contributor that hasn't been addressed, reach out on Slack to get more information and update the contributor.
|
||||
While each team member is responsible for monitoring their active issues and pull requests, the Community Engagement DRI will check in on pull requests with the `:community ` label daily to make sure everything is moving along. If there's a comment or question from the contributor that hasn't been addressed, reach out on Slack to get more information and update the contributor.
|
||||
|
||||
#### Merge Community PRs
|
||||
|
||||
|
|
@ -357,7 +149,7 @@ If you're assigned a community pull request for review, it is important to keep
|
|||
|
||||
A PR should be merged if:
|
||||
|
||||
- It's a change that is needed and useful.
|
||||
- It's a change that is needed and useful.
|
||||
- The CI is passing.
|
||||
- Tests are in place.
|
||||
- Documentation is updated.
|
||||
|
|
@ -370,7 +162,7 @@ For PRs that aren't ready to merge:
|
|||
- Offer code review and coaching to help get the PR ready to go (see note below).
|
||||
- Keep an eye out for any updates or responses.
|
||||
|
||||
> Sometimes (typically for Fleet customers), a Fleet team member may add tests and make any necessary changes to merge the PR.
|
||||
> Sometimes (typically for Fleet customers), a Fleet team member may add tests and make any necessary changes to merge the PR.
|
||||
|
||||
If everything is good to go, approve the review.
|
||||
|
||||
|
|
@ -381,7 +173,7 @@ For PRs that will not be merged:
|
|||
|
||||
## Updating Docs and FAQ
|
||||
|
||||
When someone asks a question in a public channel, it's pretty safe to assume that they aren't the only person looking for an answer to the same question. To make our docs as helpful as possible, the Community team gathers these questions and uses them to make a weekly documentation update.
|
||||
When someone asks a question in a public channel, it's pretty safe to assume that they aren't the only person looking for an answer to the same question. To make our docs as helpful as possible, the Community team gathers these questions and uses them to make a weekly documentation update.
|
||||
|
||||
Our goal is to answer every question with a link to the docs and/or result in a documentation update.
|
||||
|
||||
|
|
@ -400,13 +192,13 @@ When responding to a question or issue in the [#fleet](https://osquery.slack.com
|
|||
Every week, the Community Engagement DRI will:
|
||||
|
||||
- Create a new `Weekly Doc Update` issue on Monday and add it to the [Community board](https://github.com/orgs/fleetdm/projects/36).
|
||||
- Review the Slack Questions Spreadsheet and make sure that any necessary updates to the documentation are made.
|
||||
- Update the spreadsheet to indicate what action was taken (Doc change, FAQ added, or None) and add notes if need be.
|
||||
- Set up a single PR to update the Docs.
|
||||
- In the notes, include a list of changes made as well as a link to the related thread.
|
||||
- Review the Slack Questions Spreadsheet and make sure that any necessary updates to the documentation are made.
|
||||
- Update the spreadsheet to indicate what action was taken (Doc change, FAQ added, or None) and add notes if need be.
|
||||
- Set up a single PR to update the Docs.
|
||||
- In the notes, include a list of changes made as well as a link to the related thread.
|
||||
- Bring any questions to DevRel Office Hours (time TBD).
|
||||
- Submit the PR by the end of the day on Thursday.
|
||||
- Once the PR is approved, share in the [#fleet channel](https://osquery.slack.com/archives/C01DXJL16D8) of Osquery Slack Workspace and thank the community for being involved and asking questions.
|
||||
- Submit the PR by the end of the day on Thursday.
|
||||
- Once the PR is approved, share in the [#fleet channel](https://osquery.slack.com/archives/C01DXJL16D8) of Osquery Slack Workspace and thank the community for being involved and asking questions.
|
||||
|
||||
## Fleet swag
|
||||
|
||||
|
|
@ -420,9 +212,9 @@ Our Typeform integrations automatically populate information within the #help-sw
|
|||
|
||||
For community contributions, reach out to the contributor to thank them for their contribution, ask if they would like any swag, and fill out their information in the [Fleet swag request sheet](https://docs.google.com/spreadsheets/d/1bySsYVYHY8EjxWhhAKMLVAPLNjg3IYVNpyg50clfB6I/edit#gid=2028707729).
|
||||
|
||||
Once approved in the sheet, or submitted through [Typeform](https://admin.typeform.com/form/ZfA3sOu0/results#responses), place the order through our Printful account (credentials in 1Password) within 48 hours of submission. If available through the ordering process, add a thank you note for their contribution or request.
|
||||
Once approved in the sheet, or submitted through [Typeform](https://admin.typeform.com/form/ZfA3sOu0/results#responses), place the order through our Printful account (credentials in 1Password) within 48 hours of submission. If available through the ordering process, add a thank you note for their contribution or request.
|
||||
|
||||
When an estimated shipping date is available, notify the requestor by email with an update on shipping, thank them for being a part of the community, and provide the tracking number once shipped.
|
||||
When an estimated shipping date is available, notify the requestor by email with an update on shipping, thank them for being a part of the community, and provide the tracking number once shipped.
|
||||
|
||||
Printful order information can be found on [Printful](https://www.printful.com/dashboard/default/orders) or billing@fleetdm.com.
|
||||
|
||||
|
|
@ -432,26 +224,22 @@ At this time, double-check that information within Salesforce and Typeform is ac
|
|||
|
||||
The following table lists the Community group's rituals, frequency, and Directly Responsible Individual (DRI).
|
||||
|
||||
| Ritual | Frequency | Description | DRI |
|
||||
|:-----------------------------|:-----------------------------|:----------------------------------------------------|-------------------|
|
||||
| Community Slack | Daily | Check Fleet and osquery Slack channels for community questions, make sure questions are responded to and logged. | Kathy Satterlee |
|
||||
| Social media check-in | Daily | Check social media for community questions and make sure to respond to them. Generate dev advocacy-related content. | Kelvin Omereshone |
|
||||
| Issue check-in | Daily | Check GitHub for new issues submitted by the community, check the status of existing requests, and follow up when needed. | Kathy Satterlee |
|
||||
| Outside contributor follow-up | Weekly | Bring pull requests from outside contributors to engineering and make sure they are merged promptly and promoted. | Kathy Satterlee |
|
||||
| Documentation update | Weekly | Turn questions answered from Fleet and osquery Slack into FAQs in Fleet’s docs. | Kathy Satterlee |
|
||||
| StackOverflow | Weekly | Search StackOverflow for “osquery,” answer questions with Grammarly, and find a way to feature Fleet in your StackOverflow profile prominently. | Rotation: Community team |
|
||||
|
||||
| Ritual | Frequency | Description | DRI |
|
||||
| :---------------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
|
||||
| Community Slack | Daily | Check Fleet and osquery Slack channels for community questions, make sure questions are responded to and logged. | Kathy Satterlee |
|
||||
| Social media check-in | Daily | Check social media for community questions and make sure to respond to them. Generate dev advocacy-related content. | Kelvin Omereshone |
|
||||
| Issue check-in | Daily | Check GitHub for new issues submitted by the community, check the status of existing requests, and follow up when needed. | Kathy Satterlee |
|
||||
| Outside contributor follow-up | Weekly | Bring pull requests from outside contributors to engineering and make sure they are merged promptly and promoted. | Kathy Satterlee |
|
||||
| Documentation update | Weekly | Turn questions answered from Fleet and osquery Slack into FAQs in Fleet’s docs. | Kathy Satterlee |
|
||||
| StackOverflow | Weekly | Search StackOverflow for “osquery,” answer questions with Grammarly, and find a way to feature Fleet in your StackOverflow profile prominently. | Rotation: Community team |
|
||||
|
||||
## Slack channels
|
||||
|
||||
This group maintains the following [Slack channels](https://fleetdm.com/handbook/company#group-slack-channels):
|
||||
|
||||
| Slack channel | [DRI](https://fleetdm.com/handbook/company#group-slack-channels) |
|
||||
|:----------------------------|:--------------------------------------------------------------------|
|
||||
| `#g-community` | Kathy Satterlee
|
||||
|
||||
|
||||
|
||||
| Slack channel | [DRI](https://fleetdm.com/handbook/company#group-slack-channels) |
|
||||
| :------------- | :--------------------------------------------------------------- |
|
||||
| `#g-community` | Kathy Satterlee |
|
||||
|
||||
<meta name="maintainedBy" value="ksatter">
|
||||
<meta name="title" value="🪂 Community">
|
||||
|
|
|
|||
|
|
@ -2,29 +2,42 @@
|
|||
|
||||
## Meetings
|
||||
|
||||
### In this section
|
||||
|
||||
- [Goals](#goals)
|
||||
- [Principles](#principles])
|
||||
- [Eng Together](#eng-together)
|
||||
- [Release Retro](#release-retro)
|
||||
- [Group Weeklies](#group-weeklies)
|
||||
- [Standup](#standup)
|
||||
- [Product and Eng Weekly](#product-and-eng-weekly)
|
||||
|
||||
### Goals
|
||||
|
||||
* Stay in alignment across the whole organization.
|
||||
* Build teams, not groups of people.
|
||||
* Provide substantial time for engineers to work on "focused work."
|
||||
- Stay in alignment across the whole organization.
|
||||
- Build teams, not groups of people.
|
||||
- Provide substantial time for engineers to work on "focused work."
|
||||
|
||||
### Principles
|
||||
|
||||
* Support the [Maker Schedule](http://www.paulgraham.com/makersschedule.html) by keeping meetings to a minimum.
|
||||
* Each individual must have a weekly sync 1:1 meeting with their manager. This is key to making sure each individual has a voice within the organization.
|
||||
* Each team should have a fixed weekly sync check-in. This helps reinforce team bonds and alignment.
|
||||
* Favor async communication when possible. This is very important to make sure every stakeholder on a project can have a clear understanding of what’s happening or what was decided, without needing to attend every meeting (i.e., if a person is sick or on vacation or just life happened.)
|
||||
* If an async conversation is not proving to be effective, never hesitate to hop on or schedule a call. Always document the decisions made in a ticket, document, or whatever makes sense for the conversation.
|
||||
- Support the [Maker Schedule](http://www.paulgraham.com/makersschedule.html) by keeping meetings to a minimum.
|
||||
- Each individual must have a weekly sync 1:1 meeting with their manager. This is key to making sure each individual has a voice within the organization.
|
||||
- Each team should have a fixed weekly sync check-in. This helps reinforce team bonds and alignment.
|
||||
- Favor async communication when possible. This is very important to make sure every stakeholder on a project can have a clear understanding of what’s happening or what was decided, without needing to attend every meeting (i.e., if a person is sick or on vacation or just life happened.)
|
||||
- If an async conversation is not proving to be effective, never hesitate to hop on or schedule a call. Always document the decisions made in a ticket, document, or whatever makes sense for the conversation.
|
||||
|
||||
The following is the subset of proposed engineering meetings. Each group is free to treat these as a subset of the expected meetings and add any other meetings as they see fit.
|
||||
|
||||
### Eng together (Weekly ~ one hour)
|
||||
This is to promote cohesion across groups within the engineering team. Disseminate engineering-wide announcements.
|
||||
### Eng Together
|
||||
|
||||
This is to promote cohesion across groups within the engineering team. Disseminate engineering-wide announcements. Held weekly for one hour.
|
||||
|
||||
#### Participants
|
||||
|
||||
This includes all of engineering.
|
||||
|
||||
#### Sample agenda
|
||||
|
||||
- Announcements
|
||||
- “Show and tell”
|
||||
- Each engineer gets two minutes to explain (showing, if desired) what they are working on and why it’s important to the business and/or engineering team.
|
||||
|
|
@ -33,31 +46,38 @@ This includes all of engineering.
|
|||
- Social
|
||||
- Structured and/or unstructured social activities
|
||||
|
||||
### Release Retro (Each release ~ 30 minutes)
|
||||
Gather feedback from all participants in each release. Used to improve communication and processes.
|
||||
### Release Retro
|
||||
|
||||
Gather feedback from all participants in each release. Used to improve communication and processes. Held each release for 30 minutes.
|
||||
|
||||
This meeting will likely need to be split in the future as the number of attendees increases.
|
||||
|
||||
#### Participants
|
||||
|
||||
This would include members of each group (+ quality).
|
||||
|
||||
#### Sample agenda
|
||||
|
||||
For each attendee:
|
||||
|
||||
- What went well this release cycle?
|
||||
- What could have gone better this release cycle?
|
||||
- What should we remember next time?
|
||||
|
||||
### Group Weeklies (Weekly ~ 30 minutes - one hour)
|
||||
A chance for deeper, synchronous discussion on topics relevant to that group.
|
||||
### Group Weeklies
|
||||
|
||||
A chance for deeper, synchronous discussion on topics relevant to that group. Held weekly for 30 minutes - one hour.
|
||||
|
||||
e.g., “Interface Weekly” - “Platform Weekly” - “Agent Weekly”
|
||||
|
||||
In some groups, this may be split into smaller discussions related to the different focuses of members within the group.
|
||||
|
||||
#### Participants
|
||||
|
||||
This would include members of each group.
|
||||
|
||||
#### Sample agenda (Platform)
|
||||
|
||||
- Announcements
|
||||
- Anything at risk for the release?
|
||||
- Bug assignment
|
||||
|
|
@ -66,39 +86,47 @@ This would include members of each group.
|
|||
- MarshalJSON to hide passwords and API tokens. Thoughts?
|
||||
|
||||
#### Sample Agenda (Interface)
|
||||
|
||||
- What’s good?
|
||||
- Anything at risk for the release?
|
||||
- Bug assignment
|
||||
- Confirm response payload matches spec
|
||||
- Discuss completion of Redux removal
|
||||
|
||||
### Standup (Optional, varies by group)
|
||||
### Standup
|
||||
|
||||
This is to provide status reports, discover blockers, and keep the group in sync.
|
||||
(Optional, varies by group) This is to provide status reports, discover blockers, and keep the group in sync.
|
||||
|
||||
If desired, each group can implement daily (or some other cadence) standups. Ultimately, it’s up to the Engineering Manager to make sure that the team is communicating appropriately to deliver results.
|
||||
|
||||
#### Participants
|
||||
|
||||
This would include any members of the group.
|
||||
|
||||
### Engineering Leadership Weekly (Weekly ~ one hour)
|
||||
|
||||
Engineering leaders discuss topics of importance that week.
|
||||
|
||||
#### Participants
|
||||
|
||||
This would include the CTO + Engineering managers.
|
||||
|
||||
#### Sample agenda
|
||||
|
||||
- Fullstack engineer hiring
|
||||
- Engineering process discussion
|
||||
- Review Q2 OKRs
|
||||
|
||||
### Product/Eng Weekly (Weekly - 30 minutes)
|
||||
Engineering and Product sync on priorities for the upcoming release, surface and address any inter-group dependencies.
|
||||
### Product and Eng Weekly
|
||||
|
||||
Engineering and Product sync on priorities for the upcoming release, surface and address any inter-group dependencies. Held weekly for 30 minutes.
|
||||
|
||||
#### Participants
|
||||
|
||||
This would include the CTO + Engineering managers + PMs.
|
||||
|
||||
#### Sample agenda
|
||||
|
||||
- Plan for what's going into the next release
|
||||
- Identify inter-group dependencies
|
||||
- Ensure items are moving through architect/estimation
|
||||
|
|
@ -114,6 +142,7 @@ The current release cadence is once every three weeks and is concentrated around
|
|||
In order to make sure quality releases, Fleet has a freeze period for testing prior to each release. Effective at the start of the freeze period, new feature work will not be merged.
|
||||
|
||||
Release blocking bugs are exempt from the freeze period and are defined by the same rules as patch releases, which include:
|
||||
|
||||
1. Regressions
|
||||
2. Security concerns
|
||||
3. Issues with features targeted for current release
|
||||
|
|
@ -125,37 +154,49 @@ Non-release blocking bugs may include known issues that were not targeted for th
|
|||
Documentation on completing the release process can be found
|
||||
[here](../docs/Contributing/Releasing-Fleet.md).
|
||||
|
||||
## Oncall rotation
|
||||
## On-call rotation
|
||||
|
||||
### In this section
|
||||
|
||||
- [Responsibilities](#responsibilities)
|
||||
- [Clearing the plate](#clearing-the-plate)
|
||||
- [How to reach the on-call engineer](#how-to-reach-the-on-call-engineer)
|
||||
- [Handoff](#handoff)
|
||||
- [The rotation](#the-rotation)
|
||||
|
||||
### Responsibilities
|
||||
|
||||
During their on-call shift, engineers temporarily take on a different set of priorities and responsibilities.
|
||||
#### 1. Second-line response
|
||||
|
||||
#### Responding quickly and finding answers
|
||||
The on-call engineer is a second-line responder to questions raised by customers and community members.
|
||||
|
||||
The on-call engineer is a second-line responder to questions raised by customers and community members. We respond within 1-hour (during business hours) for interactions and ask the on-call engineer to address any questions sent their way promptly.
|
||||
The community contact (Kathy) is responsible for the first response to GitHub issues, pull requests, and Slack messages in the [#fleet channel](https://osquery.slack.com/archives/C01DXJL16D8) of osquery Slack, and other public Slacks. Kathy is also responsible for the first response to messages in private customer Slack channels.
|
||||
|
||||
Normally, the community contact (Kathy) is responsible for the first response to GitHub issues, pull requests, and Slack messages in the osquery and other public Slacks. Kathy is also responsible for the first response to messages in private customer Slack channels. When Kathy is unavailable, the on-call engineer may sometimes be asked to take over the first response duties.
|
||||
We respond within 1-hour (during business hours) for interactions and ask the on-call engineer to address any questions sent their way promptly. When Kathy is unavailable, the on-call engineer may sometimes be asked to take over the first response duties.
|
||||
|
||||
#### Reviewing pull requests
|
||||
#### 2. PR reviews
|
||||
|
||||
Some pull requests are routed through the on-call engineer for review. It is the on-call engineer's responsibility to confirm that these PRs move forward quickly (either by review with feedback or merge).
|
||||
Pull requests may be routed through the on-call engineer for review.
|
||||
|
||||
For PRs from the community, the community contact ([Kathy](https://github.com/ksatter)) will request review from the on-call. For all PRs to the Fleet documentation, the content editor ([Chris McGillicuddy](https://github.com/chris-mcgillicuddy)) will either merge (for typo fixes, when only documentation files are changed) or request a review from the current on-call (for changes to code samples, or to the meaning of the text).
|
||||
For PRs from the community, the community contact ([Kathy](https://github.com/ksatter)) will request review from the on-call. For all PRs to the Fleet documentation, the content editor ([Chris McGillicuddy](https://github.com/chris-mcgillicuddy)) will either merge (for typo fixes, when only documentation files are changed) or request a review from the current on-call (for changes to code samples, or to the meaning of the text).
|
||||
|
||||
In either case, if the on-call has the knowledge and confidence to review, they should go ahead and do so. Otherwise, they should request a review from an engineer with the appropriate domain knowledge.
|
||||
In either case, if the on-call engineer has the knowledge and confidence to review, they should go ahead and do so. Otherwise, they should request a review from an engineer with the appropriate domain knowledge. It is the on-call engineer's responsibility to confirm that these PRs are moved forward (either by review with feedback or merge).
|
||||
|
||||
#### Attending meetings
|
||||
#### 3. Customer success meetings
|
||||
|
||||
The on-call engineer is asked to attend all the customer success meetings during the week.
|
||||
|
||||
The engineer will receive calendar invitations from Tony for the appropriate meetings. Besides giving Fleet's customers access to the expertise of the people who know the Fleet product best, this has a dual purpose of providing more context for how our customers use Fleet. Also, the engineer should actively participate and provide input where appropriate (if not sure, please ask your manager or Tony).
|
||||
The engineer will receive calendar invitations from Tony for the appropriate meetings. This has a dual purpose of providing more context for how our customers use Fleet. Also, the engineer should actively participate and provide input where appropriate (if not sure, please ask your manager or Tony).
|
||||
|
||||
#### 4. Improve documentation
|
||||
|
||||
The on-call engineer is asked to read, understand, test, correct, and improve at least one doc page per week. Our goal is to 1, ensure accuracy and verify that our deployment guides and tutorials are up to date and work as expected. And 2, improve the readability, consistency, and simplicity of our documentation – with empathy towards first-time users. See [Writing documentation](#writing-documentation) for writing guidelines, and don't hesitate to reach out to [#g-digital-experience](https://fleetdm.slack.com/archives/C01GQUZ91TN) on Slack for writing support.
|
||||
|
||||
### Clearing the plate
|
||||
|
||||
Engineering managers are asked to be aware of the [on-call rotation](https://docs.google.com/document/d/1FNQdu23wc1S9Yo6x5k04uxT2RwT77CIMzLLeEI2U7JA/edit#) and schedule a light workload for engineers while they are on-call. While it varies week to week considerably, the on-call responsibilities can sometimes take up a substantial portion of the engineer's time.
|
||||
|
||||
### How to reach the oncall
|
||||
### How to reach the on-call engineer
|
||||
|
||||
Oncall engineers do not need to actively monitor Slack channels, except when called in by the Community or Customer teams. Members of those teams are instructed to `@oncall` in `#help-engineering` to get the attention of the oncall engineer to continue discussing any issues that come up. In some cases, the Community or Customer representative will continue to communicate with the requestor. In others, the oncall engineer will communicate directly (team members should use their judgment and discuss on a case-by-case basis how to best communicate with community members and customers).
|
||||
|
||||
|
|
@ -180,16 +221,18 @@ Every week, the oncall engineer changes. Here are some tips for making this hand
|
|||
See [the internal Google Doc](https://docs.google.com/document/d/1FNQdu23wc1S9Yo6x5k04uxT2RwT77CIMzLLeEI2U7JA/edit#) for the engineers in the rotation.
|
||||
|
||||
## Incident postmortems
|
||||
|
||||
At Fleet, we take customer incidents very seriously. After working with customers to resolve issues, we will conduct an internal postmortem to determine any documentation or coding changes to prevent similar incidents from happening in the future. Why? We strive to make Fleet the best osquery management platform globally, and we sincerely believe that starts with sharing lessons learned with the community to become stronger together.
|
||||
|
||||
At Fleet, we do postmortem meetings for every production incident, whether it's a customer's environment or on fleetdm.com.
|
||||
|
||||
## Outages
|
||||
At Fleet, we consider an outage to be a situation where new features or previously stable features are broken or unusable.
|
||||
- Occurences of outages are tracked in the [Outages](https://docs.google.com/spreadsheets/d/1a8rUk0pGlCPpPHAV60kCEUBLvavHHXbk_L3BI0ybME4/edit#gid=0) spreadsheet.
|
||||
- Fleet encourages embracing the inevitability of mistakes and discourages blame games.
|
||||
- Fleet stresses the critical importance of avoiding outages because they make customers' lives worse instead of better.
|
||||
|
||||
At Fleet, we consider an outage to be a situation where new features or previously stable features are broken or unusable.
|
||||
|
||||
- Occurences of outages are tracked in the [Outages](https://docs.google.com/spreadsheets/d/1a8rUk0pGlCPpPHAV60kCEUBLvavHHXbk_L3BI0ybME4/edit#gid=0) spreadsheet.
|
||||
- Fleet encourages embracing the inevitability of mistakes and discourages blame games.
|
||||
- Fleet stresses the critical importance of avoiding outages because they make customers' lives worse instead of better.
|
||||
|
||||
## Project boards
|
||||
|
||||
|
|
@ -229,6 +272,18 @@ The TLDR is: understand very well how a table will be used. If we do bulk insert
|
|||
|
||||
In particular, host_id is a foreign key we’ve been skipping in all the new additional host data tables, which is not something that comes for free, as with that, [we have to keep the data consistent by hand with cleanups](https://github.com/fleetdm/fleet/blob/main/server/datastore/mysql/hosts.go#L309-L309).
|
||||
|
||||
### In this section
|
||||
|
||||
- [Insert on duplicate update](#insert-on-duplicate-update)
|
||||
- [Host extra data and JOINs](#host-extra-data-and-joi-ns)
|
||||
- [What DB tables matter more when thinking about performance?](#what-db-tables-matter-more-when-thinking-about-performance)
|
||||
- [Expose more host data in the host listing](#expose-more-host-data-in-the-host-listing)
|
||||
- [Understand main use-cases for queries](#understand-main-use-cases-for-queries)
|
||||
- [On constantly changing data](#on-constantly-changing-data)
|
||||
- [Counts and aggregated data](#counts-and-aggregated-data)
|
||||
- [Caching data such as app config](#caching-data-such-as-app-config)
|
||||
- [Redis SCAN](#redis-scan)
|
||||
|
||||
### Insert on duplicate update
|
||||
|
||||
It’s very important to understand how a table will be used. If rows are inserted once and then updated many times, an easy reflex is to do an `INSERT … ON DUPLICATE KEY UPDATE`. While technically correct, it will be more performant to try to do an update, and if it fails because there are no rows, then do an insert for the row. This means that it’ll fail once, and then it’ll update without issues, while on the `INSERT … ON DUPLICATE KEY UPDATE`, it will try to insert, and 99% of the time, it will go into the `ON DUPLICATE KEY UPDATE`.
|
||||
|
|
@ -259,7 +314,7 @@ Solutions can become a curse too. Be mindful of when we might cross that thresho
|
|||
|
||||
### What DB tables matter more when thinking about performance?
|
||||
|
||||
While we need to be careful about handling everything in the database, not every table is the same. The host and host_* tables are the main cases where we have to be careful when using them in any way.
|
||||
While we need to be careful about handling everything in the database, not every table is the same. The host and host\_\* tables are the main cases where we have to be careful when using them in any way.
|
||||
|
||||
However, beware of tables that go through async aggregation processes (such as scheduled_query and scheduled_query_stats) or those that are read often as part of the osquery distributed/read and config endpoints.
|
||||
|
||||
|
|
@ -319,31 +374,286 @@ Another place to cache things would be Redis. The improvement here is that all i
|
|||
|
||||
Redis has solved many scaling problems in general, but it’s not devoid of scaling problems of its own. In particular, we learned that the SCAN command scans the whole key space before it does the filtering. This can be very slow, depending on the state of the system. If Redis is slow, a lot suffers from it.
|
||||
|
||||
## Fleet docs
|
||||
|
||||
Fleet documentation explains how to use, deploy, and contribute to Fleet as simply as possible. This goes a long way in driving adoption while building our community of fans.
|
||||
|
||||
### In this section
|
||||
|
||||
- [How to request a review for Markdown changes to the docs](#how-to-request-a-review-for-markdown-changes-to-the-docs)
|
||||
- [Writing documentation](#writing-documentation)
|
||||
- [Markdown](#markdown)
|
||||
- [Docs style guide](#docs-style-guide)
|
||||
- [Adding links](#adding-links)
|
||||
- [Linking to a location on GitHub](#linking-to-a-location-on-github)
|
||||
- [How to fix a broken link](#how-to-fix-a-broken-link)
|
||||
- [Page order](#page-order)
|
||||
- [Adding an image](#adding-an-image)
|
||||
- [Adding a mermaid diagram](#adding-a-mermaid-diagram)
|
||||
|
||||
### How to request a review for Markdown changes to the docs
|
||||
|
||||
When creating a pull request for Markdown changes in the docs, request a review from Desmi Dizney, who will do an editor pass, and then hand over the review to the [on-call engineer](https://fleetdm.com/handbook/engineering#oncall-rotation) if necessary.
|
||||
|
||||
### Writing documentation
|
||||
|
||||
You don’t have to be a “writer” to write documentation. Nobody knows Fleet better than the people who are building our product. That puts developers in the perfect position to show users what Fleet can do.
|
||||
|
||||
This guide will help you write docs that help users achieve their goals with Fleet.
|
||||
|
||||
#### Remember the reader
|
||||
|
||||
People come from different backgrounds. New users may not know terms that are common knowledge for seasoned developers. Since Fleet has users all over the world, English may not be their first language. Your writing must be easy for any user to understand.
|
||||
|
||||
- **Think of every user.** Define technical terms in the doc or include a link.
|
||||
- **Strive for simplicity.** Avoid complex sentences and long paragraphs.
|
||||
- **Be approachable.** Write like you’re meeting a new member of your team.
|
||||
|
||||
#### Answer the question
|
||||
|
||||
It’s what we’re all about at Fleet. People read docs in order to accomplish their goals. Those goals can vary from learning about Fleet for the first time to looking for troubleshooting tips. Make sure your doc meets the specific need of the user at that moment.
|
||||
|
||||
- **Understand the question.** Be clear about the topic you’re discussing.
|
||||
- **Narrow your focus.** Avoid explanations that distract from the main topic.
|
||||
- **No more, no less.** Use just enough information to give an accurate answer.
|
||||
|
||||
#### Follow a framework
|
||||
|
||||
Starting with a blank page can be scary. That’s why it helps to have a framework for your writing. Follow these four steps to write your docs: introduction, explanation, reference, and troubleshooting.
|
||||
|
||||
##### Introduction
|
||||
|
||||
Give an overview of the topic. You don’t need to mention everything at the beginning. Briefly establish the question you’re addressing. People want to get to the answer A.S.A.P.
|
||||
|
||||
##### Explanation
|
||||
|
||||
You’ve let users know why they’re reading your doc. It’s time to make sure they understand the topic. This will be most of your documentation. Don’t shy away from details.
|
||||
|
||||
##### Reference
|
||||
|
||||
Support your explanation with relevant references. This shows users how to put your explanation into practice. Such material will keep users coming back.
|
||||
|
||||
##### Troubleshooting
|
||||
|
||||
Nothing is perfect. Your readers understand this. Users will appreciate it if you identify common problems — and provide solutions — before they encounter these issues later.
|
||||
|
||||
#### Document every change
|
||||
|
||||
Any change to Fleet’s code should be documented, from adding patches to building features. This allows users and Fleeties to stay up to date with improvements to our product.
|
||||
|
||||
You don’t need to wait until a change has been made to write a new doc. Starting with documentation can help you discover ways to make Fleet even better.
|
||||
|
||||
Writing about how to use a new feature puts you in the shoes of the user. If something seems complicated, you have the opportunity to improve it — before commiting a line of code.
|
||||
|
||||
### Markdown
|
||||
|
||||
Fleet's documentation and handbook are written in [Markdown](https://about.gitlab.com/handbook/markdown-guide/). Using Markdown lets us keep our documentation consistently formatted and viewable directly from the Fleet GitHub repo. The Markdown files in the `/docs` and `/handbook` folders are converted to HTML for the Fleet website.
|
||||
|
||||
When making changes to the Fleet docs or handbook, there are a few differences in how the Markdown will render on GitHub and the Fleet website.
|
||||
|
||||
#### Linebreaks and newlines
|
||||
|
||||
Any time you need to add a line break in Markdown, you should add a new line. It is vital to make sure paragraphs are separated by new lines. Otherwise, they will render as the same HTML element.
|
||||
|
||||
For example, if you were adding this section to the docs:
|
||||
|
||||
```
|
||||
line one
|
||||
line two
|
||||
```
|
||||
|
||||
The Markdown would render on the Fleet website as
|
||||
|
||||
line one
|
||||
line two
|
||||
|
||||
To make sure formatting is consistent across GitHub and the Fleet website, you need to add a new line anywhere you want a line break. For example, if we separate the lines with a new line:
|
||||
|
||||
```
|
||||
line one
|
||||
|
||||
line two
|
||||
```
|
||||
|
||||
The Markdown will render correctly as
|
||||
|
||||
line one
|
||||
|
||||
line two
|
||||
|
||||
#### Ordered lists
|
||||
|
||||
Content nested within an ordered list needs to be indented. If the list is not formatted correctly, the number will reset on each list item.
|
||||
|
||||
For example, this list:
|
||||
|
||||
```
|
||||
1. Item one
|
||||
|
||||
Paragraph about item one
|
||||
|
||||
2. Item two
|
||||
```
|
||||
|
||||
On the Fleet website, this ordered list would be rendered as
|
||||
|
||||
1. Item one
|
||||
|
||||
Paragraph about item one
|
||||
|
||||
2. Item two
|
||||
|
||||
To make sure that ordered lists increment on the Fleet website, you can indent the content nested within the list. For example, the same ordered list with indentation:
|
||||
|
||||
```
|
||||
1. Item one
|
||||
|
||||
Paragraph about item one
|
||||
|
||||
2. Item two
|
||||
```
|
||||
|
||||
This ordered list will render correctly as
|
||||
|
||||
1. Item one
|
||||
|
||||
Paragraph about item one
|
||||
|
||||
2. Item two
|
||||
|
||||
### Docs style guide
|
||||
|
||||
#### Headings
|
||||
|
||||
Headings help readers quickly scan content to find what they need. Organize page content using clear headings specific to the topic they describe.
|
||||
|
||||
Keep headings brief, organized, and in a logical order:
|
||||
|
||||
- H1: Page title
|
||||
- H2: Main headings
|
||||
- H3: Subheadings
|
||||
- H4: Sub-subheadings (headings nested under subheadings)
|
||||
|
||||
Try to stay within three or four heading levels. Complicated documents may use more, but pages with a simpler structure are easier to read.
|
||||
|
||||
#### SQL statements
|
||||
|
||||
When adding SQL statements, all SQL reserved words should be uppercase, and all identifiers (such as tables and columns) should be lowercase. Here is an example:
|
||||
|
||||
```sql
|
||||
SELECT days, hours, total_seconds FROM uptime;
|
||||
```
|
||||
|
||||
### Adding links
|
||||
|
||||
You can link documentation pages to each other using relative paths. For example, in `docs/Using-Fleet/Fleet-UI.md`, you can link to `docs/Using-Fleet/Permissions.md` by writing `[permissions](./Permissions.md)`. This will automatically be transformed into the appropriate URL for `fleetdm.com/docs`.
|
||||
|
||||
However, the `fleetdm.com/docs` compilation process does not account for relative links to directories **outside** of `/docs`.
|
||||
This is why it’s essential to follow the file path exactly when adding a link to Fleet docs.
|
||||
When directly linking to a specific section, always format the spaces within a section name to use a hyphen instead of an underscore. For example, when linking to the `osquery_result_log_plugin` section of the configuration reference docs, use a relative link like the following: `./Configuration.md#osquery-result-log-plugin`.
|
||||
|
||||
### Linking to a location on GitHub
|
||||
|
||||
When adding a link to a location on GitHub outside of `/docs`, be sure to use the canonical form of the URL.
|
||||
|
||||
Navigate to the file's location on GitHub, and press "y" to transform the URL into its canonical form.
|
||||
|
||||
### How to fix a broken link
|
||||
|
||||
For instances when a broken link is discovered on fleetdm.com, always check if the link is a relative link to a directory outside of `/docs`.
|
||||
|
||||
An example of a link that lives outside of `/docs` is:
|
||||
|
||||
```
|
||||
../../tools/app/prometheus
|
||||
```
|
||||
|
||||
If the link lives outside `/docs`, head to the file's location on GitHub (in this case, [https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)](https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)), and press "y" to transform the URL into its canonical form (a version of the link that will always point to the same version of the file) ([https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml](https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml)). Replace the relative link with this link in the Markdown file.
|
||||
|
||||
> Note that the instructions above also apply to adding links in the Fleet handbook.
|
||||
|
||||
### Page order
|
||||
|
||||
The order we display documentation pages on fleetdm.com is determined by `pageOrderInSection` meta tags. These pages are sorted in their respective sections in **ascending** order by the `pageOrderInSection` value. Every Markdown file (except readme and faq pages) in the `docs/` folder must have a meta tag with a positive 'pageOrderInSection' value.
|
||||
|
||||
We leave large gaps between values to make future changes easier. For example, the first page in the "Using Fleet" section of the docs has a `pageOrderInSection` value of 100, and the next page has a value of 200. The significant difference between values allows us to add, remove and reorder pages without changing the value of multiple pages at a time.
|
||||
|
||||
When adding or reordering a page, try to leave as much room between values as possible. If you were adding a new page that would go between the two pages from the example above, you would add `<meta name="pageOrderInSection" value="150">` to the page.
|
||||
|
||||
### Adding an image
|
||||
|
||||
Try to keep images in the docs at a minimum. Images can be a quick way to help users understand a concept or direct them towards a specific user interface(UI) element. Still, too many can make the documentation feel cluttered and more difficult to maintain.
|
||||
|
||||
When adding images to the Fleet documentation, follow these guidelines:
|
||||
|
||||
- UI screenshots should be a 4:3 aspect ratio (1280x960). This is an optimal size for the container width of the docs and ensures that content in screenshots is as clear as possible to view in the docs (and especially on mobile devices).
|
||||
- You can set up a custom preset in the Google Chrome device toolbar (in Developer Tools) to quickly adjust your browser to the correct size for taking a screenshot.
|
||||
- Keep the images as simple as possible to maintain. Screenshots can get out of date quickly as UIs change.
|
||||
- Exclude unnecessary images. Images should be used to help emphasize information in the docs, not replace it.
|
||||
- Minimize images per doc page. For doc maintainers and users, more than one or two per page can get overwhelming.
|
||||
- The goal is for the docs to look good on every form factor, from 320px window width all the way up to infinity. Full window screenshots and images with too much padding on the sides will be less than the width of the user's screen. When adding a large image, make sure it is easily readable at all widths.
|
||||
|
||||
Images can be added to the docs using the Markdown image link format, e.g., ``
|
||||
The images used in the docs live in `docs/images/`. Note that you must provide the URL of the image in the Fleet GitHub repo for it to display properly on both GitHub and the Fleet website.
|
||||
|
||||
> Note that the instructions above also apply to adding images in the Fleet handbook.
|
||||
|
||||
### Adding a mermaid diagram
|
||||
|
||||
The Fleet Docs support diagrams that are written in mermaid.js syntax. Take a look at the [Mermaid docs](https://mermaid-js.github.io/mermaid/#/README) to learn about the syntax language and what types of diagrams you can display.
|
||||
|
||||
To add a mermaid diagram to the docs, you need to add a code block and specify that it is written in the mermaid language by adding `mermaid` to the opening backticks (i.e., ` ```mermaid`).
|
||||
|
||||
For example, the following code block is a mermaid diagram that has **not** been specified as a mermaid code block:
|
||||
|
||||
```
|
||||
graph TD;
|
||||
A-->D
|
||||
B-->D
|
||||
C-->D
|
||||
D-->E
|
||||
```
|
||||
|
||||
Once we specify the `mermaid` as the language in the code block, it will render as a mermaid diagram on fleetdm.com and GitHub.
|
||||
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->D
|
||||
B-->D
|
||||
C-->D
|
||||
D-->E
|
||||
```
|
||||
|
||||
If the mermaid syntax is incorrect, the diagram will be replaced with an image displaying an error, as shown in the following example where the code block was written with **intentional** syntax errors:
|
||||
|
||||
```mermaid
|
||||
graph TD;
|
||||
A--D
|
||||
```
|
||||
|
||||
## Rituals
|
||||
|
||||
The following rituals are engaged in by the directly responsible individual (DRI) and at the frequency specified for the ritual.
|
||||
The following rituals are engaged in by the directly responsible individual (DRI) and at the frequency specified for the ritual.
|
||||
|
||||
| Ritual | Frequency | Description | DRI |
|
||||
|:-----------------------------|:-----------------------------|:----------------------------------------------------|-------------------|
|
||||
| Pull request review | Daily | Engineers go through pull requests for which their review has been requested. | Zach Wasserman |
|
||||
| Engineering group discussions | Weekly | See "Group Weeklies". | Zach Wasserman |
|
||||
| On-call handoff | Weekly | Hand off the on-call engineering responsibilities to the next on-call engineer. | Zach Wasserman |
|
||||
| Release ritual | Every three weeks | Go through the process of releasing the next iteration of Fleet. | Zach Wasserman |
|
||||
| Create patch release branch | Every patch release | Go through the process of creating a patch release branch, cherry picking commits, and pushing the branch to github.com/fleetdm/fleet. | Luke Heath |
|
||||
| Ritual | Frequency | Description | DRI |
|
||||
| :---------------------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
|
||||
| Pull request review | Daily | Engineers go through pull requests for which their review has been requested. | Zach Wasserman |
|
||||
| Engineering group discussions | Weekly | See "Group Weeklies". | Zach Wasserman |
|
||||
| On-call handoff | Weekly | Hand off the on-call engineering responsibilities to the next on-call engineer. | Zach Wasserman |
|
||||
| Release ritual | Every three weeks | Go through the process of releasing the next iteration of Fleet. | Zach Wasserman |
|
||||
| Create patch release branch | Every patch release | Go through the process of creating a patch release branch, cherry picking commits, and pushing the branch to github.com/fleetdm/fleet. | Luke Heath |
|
||||
|
||||
## Slack channels
|
||||
|
||||
The following [Slack channels are maintained](https://fleetdm.com/handbook/company#group-slack-channels) by this group:
|
||||
|
||||
| Slack channel | [DRI](https://fleetdm.com/handbook/company#why-group-slack-channels) |
|
||||
|:------------------------------------|:--------------------------------------------------------------------|
|
||||
| `#help-engineering` | Zach Wasserman
|
||||
| `#g-platform` | Tomás Touceda
|
||||
| `#g-interface` | Luke Heath
|
||||
| `#g-agent` | Zach Wasserman
|
||||
| `#_pov-environments` | Ben Edwards
|
||||
|
||||
| Slack channel | [DRI](https://fleetdm.com/handbook/company#why-group-slack-channels) |
|
||||
| :------------------- | :------------------------------------------------------------------- |
|
||||
| `#help-engineering` | Zach Wasserman |
|
||||
| `#g-platform` | Tomás Touceda |
|
||||
| `#g-interface` | Luke Heath |
|
||||
| `#g-agent` | Zach Wasserman |
|
||||
| `#_pov-environments` | Ben Edwards |
|
||||
|
||||
<meta name="maintainedBy" value="zwass">
|
||||
<meta name="title" value="🚀 Engineering">
|
||||
|
|
|
|||
Loading…
Reference in a new issue