Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc: add migration warning to updating release system and elf programs #15378

Merged
merged 1 commit into from
Dec 29, 2024

Conversation

lvanasse
Copy link
Contributor

Summary

Add a migration warning to the update release system and the elf programs documentation pages. This is just to add a paper trail from where the documentation originate in case of error during the migration process.

Impact

Add warning section in the documentation to refer to the original wiki page in the official wiki. But nothing special

Testing

Build and validated locally with make autobuild

@github-actions github-actions bot added Area: Documentation Improvements or additions to documentation Size: S The size of the change in this PR is small labels Dec 29, 2024
@nuttxpr
Copy link

nuttxpr commented Dec 29, 2024

[Experimental Bot, please feedback here]

No, this PR description does not fully meet the NuttX requirements. While it provides a summary and mentions testing, it lacks crucial details. Here's a breakdown of the missing information:

  • Summary: While it explains the "what," it lacks the "why." Why is this migration warning necessary? What problem does it solve? What is the migration about? The summary should clearly state the motivation behind the change. It also lacks references to related issues, if any.
  • Impact: The impact section is too vague. While it mentions documentation changes, it doesn't specify which documentation files are modified. All other impact categories are simply implied as "NO" but should be explicitly stated as such for clarity. For example:
    • Impact on user: NO
    • Impact on build: NO
    • ...and so on for all categories.
  • Testing: "Validated locally with make autobuild" is insufficient. Provide specific details:
    • Build Host(s): Specify your OS, CPU architecture, and compiler version.
    • Target(s): Which architecture(s) and board/config combinations did you test on? Just stating make autobuild doesn't say what was built.
    • Logs: The requirement clearly asks for "Testing logs before change" and "Testing logs after change." These are missing entirely. Even if there's no functional change, showing a successful build before and after the documentation change is good practice.

Example of how to improve the PR description:

Summary

This PR adds a migration warning to the update release system and the ELF programs documentation pages. This is necessary to provide users with a clear reference to the official wiki page outlining the migration process for [briefly explain what is being migrated, e.g., the new configuration system]. This addresses the potential for confusion and errors during the migration, ensuring users have easy access to the definitive migration guide. (Related Issue: # if applicable)

Impact

  • Is new feature added? NO
  • Is existing feature changed? NO
  • Impact on user: NO (Only documentation is changed to provide additional guidance).
  • Impact on build: NO
  • Impact on hardware: NO
  • Impact on documentation: YES (Added a warning section to docs/update_release_system.txt and docs/elf_programs.txt referencing the wiki page at [link to wiki page]).
  • Impact on security: NO
  • Impact on compatibility: NO
  • Anything else to consider: NO

Testing

I confirm that changes are verified on local setup and works as intended:

  • Build Host(s): Linux (Ubuntu 20.04), x86_64, GCC 9.4.0
  • Target(s): sim:nsh_romfsim

Testing logs before change:

make autobuild CONFIG_SIM=y CONFIG_NSH_ROMFSIM=y
... (relevant build output showing successful build)

Testing logs after change:

make autobuild CONFIG_SIM=y CONFIG_NSH_ROMFSIM=y
... (relevant build output showing successful build)

Add a migration warning to the update release system and the elf
programs documentation pages. This is just to add a papertrail from
where the documentation originate in case of error during the migration
process. Also fix a bit of formatting in the pages
@lvanasse lvanasse force-pushed the doc-migration-7-warning branch from 8d35d59 to aa635f8 Compare December 29, 2024 14:43
@anchao anchao merged commit b02a075 into apache:master Dec 29, 2024
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Area: Documentation Improvements or additions to documentation Size: S The size of the change in this PR is small
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants