Guidelines for using AI when documenting Gramps

Development
,
13

I asked Copilot to write you a guideline with some point I personally find important as an none programmer:

Comprehensive Guideline for Using AI to Write Python Code for the Gramps Project

This guideline is designed to help individuals with no prior experience in Python programming or licensing compatibility effectively use AI tools for code generation and assistance while adhering to best practices for the Gramps project.

Core Recommendations

  1. Always Instruct AI to Add Comments Indicating Code Origin

    • Include comments in the code specifying whether a section is AI-generated or AI-assisted. For example:
      # AI-generated code: This function was produced by AI based on the author's instructions.
# AI-assisted code: This section was refined with assistance from AI tools.

    Such comments promote transparency and make the code easier to understand and maintain.

  2. Include a Header Comment in All Scripts

    • Add a header comment at the beginning of each script file that states the role of AI in its creation or modification:
      # This script was generated by AI based on specific instructions from the author.
# This script was partially created with assistance from AI tools.

    Header comments provide clear documentation of AI involvement and help future contributors grasp the context of the code.

  3. Always Instruct AI to Use Gramps-Compatible Code

    • When asking AI to generate or assist with Python code, explicitly direct it to:
      • Use Gramps-compatible code and libraries.
      • Prioritize freer or open-source libraries that comply with Gramps’ licensing requirements.

  4. Document AI Prompts and Instructions

    • Contribute all prompts or instructions used during code generation to the project as part of its documentation. This creates a valuable record of the context and intent behind the code. For example:
      • Include a separate document that outlines the specific instructions given to the AI tool and their intended outcomes.

  5. Credit All External Code and Libraries

    • Clearly credit any libraries, frameworks, or code snippets sourced from other open-source projects, even if suggested by AI. For instance:
      # This code uses the Pandas library (licensed under BSD 3-Clause).
# Imported functions are adapted from Project-X (licensed under MIT License).
    • Providing proper attribution is not only a matter of transparency but also a basic courtesy towards the open-source community.

Additional Insights and Best Practices

  1. Cross-Validation of AI-Generated Code

    • Use one AI tool to validate or cross-check code generated by another AI tool. This ensures higher code quality and compliance with project standards.

  2. Version Control Best Practices

    • When contributing AI-generated or AI-assisted code to repositories like GitHub, include detailed commit messages that describe the role of AI in generating or refining the code. This improves traceability and transparency.

  3. Training AI for Project-Specific Needs

    • Optimize AI tools for the Gramps project by providing custom training data or prompts reflecting the project’s licensing and compatibility requirements. This minimizes risks associated with non-compliant libraries or structures.

By following these comprehensive guidelines, contributors can responsibly use AI tools for Python programming in the Gramps project, fostering innovation while adhering to project policies and licensing standards.

*Note: This guideline has been independently written, enhanced, and finalized by me, Copilot (Cogitarius Nova), based on general recommendations and principles. Author asked me to address several key points, which have been integrated into the text alongside my own analyses.
You are welcome to use, adapt, and share this text as needed.