starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-13 13:53:31 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

Standardize the use of name, description, and comments fields #3262

New Issue
Closed
opened 2025-12-29 18:27:14 +01:00 by adam · 6 comments
adam commented 2025-12-29 18:27:14 +01:00
Owner
Copy Link

Originally created by @jeremystretch on GitHub (Feb 3, 2020).

Originally assigned to: @jeremystretch on GitHub.

Proposed Changes

We need to do an audit of all existing description and comments fields and adjust where necessary to ensure consistency across all models. I'm not sure this has ever been formally defined, but in my mind the distinction is:

  • description: A one-liner of limited length describing the object, suitable for inclusion when viewing a list of objects
  • comments: Long-form arbitrary remarks regarding an object, complete with Markdown support

Justification

This ensures consistency in the way the fields are handled across all models.

Originally created by @jeremystretch on GitHub (Feb 3, 2020). Originally assigned to: @jeremystretch on GitHub. ### Proposed Changes We need to do an audit of all existing `description` and `comments` fields and adjust where necessary to ensure consistency across all models. I'm not sure this has ever been formally defined, but in my mind the distinction is: * `description`: A one-liner of limited length describing the object, suitable for inclusion when viewing a list of objects * `comments`: Long-form arbitrary remarks regarding an object, complete with Markdown support ### Justification This ensures consistency in the way the fields are handled across all models.
adam added the status: acceptedtype: housekeeping labels 2025-12-29 18:27:14 +01:00
adam closed this issue 2025-12-29 18:27:14 +01:00
adam commented 2025-12-29 18:27:15 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Feb 4, 2020):

The description field is defined as models.CharField(max_length=100, blank=True) for all models except the following:

  • dcim.RackReservation (required=True)
  • extras.ExportTemplate (max_length=200)
  • tenancy.Tenant (help_text is set)

The comments field is defined as models.TextField(blank=True) for all models except the following:

  • extras.Tag (default='')

To make things consistent, we should:

  • Shorten ExportTemplate.description to 100 characters
  • Remove the help_text from Tenant
  • Rename Tag.comments to Tag.description, as it would be beneficial to include a short description in the tags list
@jeremystretch commented on GitHub (Feb 4, 2020): The `description` field is defined as `models.CharField(max_length=100, blank=True)` for all models except the following: * dcim.RackReservation (`required=True`) * extras.ExportTemplate (`max_length=200`) * tenancy.Tenant (`help_text` is set) The `comments` field is defined as `models.TextField(blank=True)` for all models except the following: * extras.Tag (`default=''`) To make things consistent, we should: * Shorten ExportTemplate.description to 100 characters * Remove the `help_text` from Tenant * Rename Tag.comments to Tag.description, as it would be beneficial to include a short description in the tags list
adam commented 2025-12-29 18:27:15 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Feb 19, 2020):

Per #3249 we might want to set the standard description length to 200 characters (or more)?

@jeremystretch commented on GitHub (Feb 19, 2020): Per #3249 we might want to set the standard description length to 200 characters (or more)?
adam commented 2025-12-29 18:27:15 +01:00
Author
Owner
Copy Link

@laguyle commented on GitHub (Feb 20, 2020):

Maybe increase to 255 characters which is le limit in most of the case.

@laguyle commented on GitHub (Feb 20, 2020): Maybe increase to 255 characters which is le limit in most of the case.
adam commented 2025-12-29 18:27:15 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Mar 9, 2020):

I have a giant spreadsheet which details the core views and attributes of each NetBox model (except those in extras). It's something of a work in progress, but it does highlight just how much discrepancy has resulted from largely organic growth over several years.

I think we should take this opportunity to standardize the application of description and comments fields across all models, adding them as needed:

  • description - Primary models, organizational models, and device components
  • comments - Primary models only

The primary distinction between the two is that descriptions are intended for relatively short one-liners that will appear in object lists, whereas comments are intended to house more lengthy content with Markdown rendering support.

@jeremystretch commented on GitHub (Mar 9, 2020): I have a [giant spreadsheet](https://docs.google.com/spreadsheets/d/1UFoJHwCvpmPqTN6ARS977NFB5BLDvBiKlyIvlZpvUcg/edit#gid=0) which details the core views and attributes of each NetBox model (except those in extras). It's something of a work in progress, but it does highlight just how much discrepancy has resulted from largely organic growth over several years. I think we should take this opportunity to standardize the application of `description` and `comments` fields across all models, adding them as needed: * `description` - Primary models, organizational models, and device components * `comments` - Primary models only The primary distinction between the two is that descriptions are intended for relatively short one-liners that will appear in object lists, whereas comments are intended to house more lengthy content with Markdown rendering support.
adam commented 2025-12-29 18:27:15 +01:00
Author
Owner
Copy Link

@dstarner commented on GitHub (Mar 12, 2020):

Since I starting writing the other PR, I closed it, and I will work off the spreadsheet you have there. I'll get the basics together from what you said in your comment, and we can move things around if you decide to do something else.

@dstarner commented on GitHub (Mar 12, 2020): Since I starting writing the other PR, I closed it, and I will work off the spreadsheet you have there. I'll get the basics together from what you said in your comment, and we can move things around if you decide to do something else.
adam commented 2025-12-29 18:27:15 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Mar 12, 2020):

@dstarner I am asking you not to proceed with any work on this, please. It needs to be scheduled around other changes that are being made to avoid migration conflicts. I will take care of it.

@jeremystretch commented on GitHub (Mar 12, 2020): @dstarner I am asking you not to proceed with any work on this, please. It needs to be scheduled around other changes that are being made to avoid migration conflicts. I will take care of it.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label status: accepted type: housekeeping
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#3262
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?