fleet/handbook/product.md

Fleet EE

Communicating design changes to Engineering

For something NEW that has been added to Figma Fleet EE (current, dev-ready):

1. Create a new GitHub issue
2. Detail the required changes (including page links to the relevant layouts), then assign it to the “Initiatives” project.

NOTE: Artwork and layouts in Figma Fleet EE (current, dev-ready) are final assets, ready for implementation. Therefore, it’s important NOT to use the “idea” label, as designs in this document are more than ideas - they are something that WILL be implemented._

3. Navigate to the Initiatives project, and hit “+ Add cards”, pick the new issue, and drag it into the “🤩Inspire me” column.

Communicating unplanned design changes

For issues related to something that was ALREADY in Figma Fleet EE (current, dev-ready), but implemented differently, e.g, padding/spacing inconsistency etc. Create a bug issue and detail the required changes.

Fleet docs

Adding a link to the Fleet docs

You can link documentation pages to each other using relative paths. For example, in docs/1-Using-Fleet/1-Fleet-UI.md, you can link to docs/1-Using-Fleet/9-Permissions.md by writing [permissions](./9-Permissions.md). This will be automatically 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. Therefore, when adding a link to Fleet docs, it is important to always use the absolute file path.

Linking to a location on GitHub

When adding a link to a location on GitHub that is outside of /docs, be sure to use the canonical form of the URL.

To do this, 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 in which a broken link is discovered on fleetdm.com, 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)), and press "y" to transform the URL into its canonical form (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.

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 a user understand a concept or direct them towards a specific UI element, but too many can make the documentation feel cluttered and more difficult to maintain.

When adding images to the Fleet documentation, follow these guidelines:

• Keep the images as simple as possible to maintain (screenshots can get out of date quickly as UIs change)
• Exclude unnecessary images. An image should be used to help emphasize information in the docs, not replace it.
• Minimize images per doc page. More than one or two per page can get overwhelming, for doc maintainers and users.
• The goal is for the docs to look good on every form factor, from 320px window width all the way up to infinity and beyond. 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 that it is easily readable at all widths.

Images can be added to the docs using the Markdown image link format, e.g. ![Schedule Query Sidebar](https://raw.githubusercontent.com/fleetdm/fleet/main/docs/images/schedule-query-sidebar.png) 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.

Manual QA

This living document outlines the manual quality assurance process conducted to ensure each release of Fleet meets organization standards.

All steps should be conducted during each QA pass. All steps are possible with fleetctl preview. In order to target a specific version of fleetctl preview, the tag argument can be used together with the commit you are targeting as long as that commit is represented by a tag in docker hub. Without tag argument, fleetctl preview defaults to latest stable.

As new features are added to Fleet, new steps and flows will be added.

Collecting bugs

The goal of manual QA is to catch unexpected behavior prior to release. All Manual QA steps should be possible using fleetctl preview. Please refer to docs/03-Contributing/02-Testing.md for flows that cannot be completed using fleetctl preview.

Please start the manual QA process by creating a blank GitHub issue. As you complete each of the flows, record a list of the bugs you encounter in this new issue. Each item in this list should contain one sentence describing the bug and a screenshot if the item is a frontend bug.

Fleet UI

For all following flows, please refer to the permissions documentation to ensure that actions are limited to the appropriate user type. Any users with access beyond what this document lists as availale should be considered a bug and reported for either documentation updates or investigation.

Set up flow

Successfully set up fleetctl preview using the preview steps outlined here

Login and logout flow

Successfully logout and then login to your local Fleet.

Host details page

Select a host from the "Hosts" table as a global user with the Maintainer role. You may create a user with a fake email for this purpose.

You should be able to see and select the "Delete" button on this host's Host details page.

You should be able to see and select the "Query" button on this host's Host details page.

Label flow

Flow is covered by e2e testing

Create a new label by selecting "Add a new label" on the Hosts page. Make sure it correctly filters the host on the hosts page.

Edit this label. Confirm users can only edit the "Name" and "Description" fields for a label. Users cannot edit the "Query" field because label queries are immutable.

Delete this label.

Query flow

Flow is covered by e2e testing

Create a new saved query.

Run this query as a live query against your local machine.

Edit this query and then delete this query.

Pack flow

Flow is covered by e2e testing

Create a new pack (under Schedule/advanced).

Add a query as a saved query to the pack. Remove this query. Delete the pack.

My account flow

Head to the My account page by selecting the dropdown icon next to your avatar in the top navigation. Select "My account" and successfully update your password. Please do this with an extra user created for this purpose to maintain accessibility of fleetctl preview admin user.

fleetctl CLI

Set up flow

Successfully set up Fleet by running the fleetctl setup command.

You may have to wipe your local MySQL database in order to successfully set up Fleet. Check out the Clear your local MySQL database section of this document for instructions.

Login and logout flow

Successfully login by running the fleetctl login command.

Successfully logout by running the fleetctl logout command. Then, log in again.

Hosts

Run the fleetctl get hosts command.

You should see your local machine returned. If your host isn't showing up, you may have to reenroll your local machine. Check out the Orbit for osquery documentation for instructions on generating and installing an Orbit package.

Query flow

Apply the standard query library by running the following command:

fleetctl apply -f docs/1-Using-Fleet/standard-query-library/standard-query-library.yml

Make sure all queries were successfully added by running the following command:

fleetctl get queries

Run the "Get the version of the resident operating system" query against your local machine by running the following command:

fleetctl query --hosts <your-local-machine-here> --query-name "Get the version of the resident operating system"

Pack flow

Apply a pack by running the following commands:

fleetctl apply -f docs/1-Using-Fleet/configuration-files/multi-file-configuration/queries.yml

fleetctl apply -f docs/1-Using-Fleet/configuration-files/multi-file-configuration/pack.yml

Make sure the pack was successfully added by running the following command:

fleetctl get packs

Organization settings flow

Apply organization settings by running the following command:

fleetctl apply -f docs/1-Using-Fleet/configuration-files/multi-file-configuration/organization-settings.yml

Manage users flow

Create a new user by running the fleetctl user create command.

Logout of your current user and log in with the newly created user.

Release process

This section outlines the release process at Fleet.

The current release cadence is once every 3 weeks and concentrated around Wednesdays.

• Blog post

Blog post

Fleet posts a release blogpost, to the Fleet blog, on the same day a new minor or major release goes out.

Patch releases do not have a release blogpost.

Check out the Fleet 4.1.0 blog post for an example release blogpost. The suggested format of a release blogpost is the following:

Title - "Fleet <insert Fleet version here>

Description - "Fleet <insert Fleet version here> released with <insert list of primary features here>

Main image - This is the image that Medium will use as the thumbnail and link preview for the blogpost.

Summary - This section includes 3-4 sentences that answers the 'what?' and 'why should the user care?' questions for the primary features.

Link to release notes - One sentence that includes a link to the GitHub release page.

Primary features - Includes the each primary feature's name, availability (Free v. Premium), image/gif, and 3-4 sentences that answer the 'why should the user care?' and 'how do I find this feature?' questions.

More improvements - Includes each additional feature's name, availability (Free v. Premium), and 1-2 sentences that answer the 'why should the user care?' questions.

Upgrade plan - Once sentence that links to user to the upgrading Fleet documentation here: https://github.com/fleetdm/fleet/blob/main/docs/01-Using-Fleet/08-Updating-Fleet.md

Manual QA

After all changes required for release have been merged into the main branch, the individual tasked with managing the release should perform a manual quality assurance pass.

Documentation on conducting the manual QA pass can be found here.

Release day

Documentation on completing the release process can be found here.

Support process

This section outlines the customer and community support process at Fleet.

The support process is accomplished via an on-call rotation and the weekly on-call retro meeting.

The individual on-call is responsible for responding to Slack comments, Slack threads, and GitHub issues raised by customers and the community.

The daily standup meeting at Fleet provides time to discuss highlights and answer the following questions about the previous week's on-call:

1. What went well?

2. What could have gone better?

3. What should we remember next time?

This way, the Fleet team can constantly improve the effectiveness and experience during future on-call rotations.

Goals

• Get familiar with and stay abreast of what our community wants and the problems they're having.

• Make people feel heard and understood.

• Celebrate contributions.

• Triage bugs, identify community feature requests, community pull requests and community questions.

How?

• No matter what, folks who post a new comment in Slack or issue in GitHub get a response from the individual on-call within 1 business day. The response doesn't need to include an immediate answer.

• The individual on-call is responsible to either schedule a 10 minute call or join the 🧩 Product meeting to ask questions they were unable to answer. If a response is needed quicker, you can always DM Fleet team members in Slack. This way, people get answers within 1 business day.

• If you do not understand the question or comment raised, request more details to best understand the next steps.

• If an appropriate response is outside your scope, please post to #oncall-chatter, a confidential Slack channel in the Fleet Slack workspace.

• If the comment appears to be a feature request in a customer channel, please post a link to the customer's comment in #oncall-chatter. This way, an individual on the Product team can collect relevant information and file a GitHub issue.

• If things get heated, remember to stay positive and helpful. If you aren't sure how best to respond in a positive way, or if you see behavior that violates the Fleet code of conduct, get help.

Requesting more details

Typically, the questions, bug reports, and feature requests raised by members of the community will be missing helpful context, recreation steps, or motivations respectively.

❓ For questions that you don't immediately know the answer to, it's helpful to ask follow up questions to receive additional context.

• Let's say a community member asks the question "How do I do X in Fleet?" A follow question could be "what are you attempting to accomplish by doing X?"
• This way, you now has additional details when the primary question is brought to the Roundup meeting. In addition, the community member receives a response and feels heard.

🦟 For bug reports, it's helpful to ask for recreation steps so you're later able to verify the bug exists.

• Let's say a community member submits a bug report. An example follow up question could be "Can you please walk me through how you encountered this issue so that I can attempt to recreate it?"
• This way, you now have steps the verify whether the bug exists in Fleet or if the issue is specific to the community member's environment. If the latter, you now have additional information for further investigation and question asking.

💡 For feature requests, it's helpful to ask follow up questions in an attempt to understand the "why?" or underlying motivation behind the request.

• Let's say a community member submits the feature request "I want the ability to do X in Fleet." A follow up question could be "If you were able to do X in Fleet, what's the next action you would take?" or "Why do you want to do X in Fleet?."
• Both of these questions provide helpful context on the underlying motivation behind the feature request when it is brought to the Roundup meeting. In addition, the community member receives a response and feels heard.

New feature request issues

After requesting more details, please add the milestone associated with the current time we are along the roadmap timeline. For example, if the current date is June 25, 2021, we would add the H1 2021 milestone to the issue.

Feature request issues automatically include the "idea" label. The "idea" label provides the signal that this issue is an item the Fleet team would like to discuss at a later date. The time of discussion is indicated by the issue's milestones.

Closing issues

It is often a good idea to let the original poster (OP) close their issue themselves, since they are usually well equipped to decide whether the issue is resolved. In some cases, circling back with the OP can be impractical, and for the sake of speed issues might get closed.

Keep in mind that this can feel jarring to the OP. The effect is worse if issues are closed automatically by a bot (See balderashy/sails#3423 and balderdashy/sails#4057 for examples of this.)

To provide another way of tracking status without closing issues altogether, consider using the green labels that begin with "+". To explore them, type + from GitHub's label picker.

Sources

There are four sources that the individual on-call should monitor for activity:

1. Customer Slack channels - Found under the "Connections" section in Slack. These channels are usually titled "at-insert-customer-name-here"

2. Community chatroom - https://osquery.slack.com, #fleet channel

3. Reported bugs - GitHub issues with the "bug" and ":reproduce" label. Please remove the ":reproduce" label after you've followed up in the issue.

4. Pull requests opened by the community - GitHub open pull requests

Resources

There are several locations in Fleet's public and internal documentation that can be helpful when answering questions raised by the community:

1. The frequently asked question (FAQ) documents in each section found in the /docs folder. These documents are the Using Fleet FAQ, Deploying FAQ, and Contributing FAQ.

2. The Internal FAQ document.