25b758805c
This pull request introduces several documentation improvements and adds comprehensive Copilot and agent instruction files to the al-folio repository. The most significant changes are the addition of repository-wide and path-specific Copilot instructions, updates to agent documentation to reference these instructions, and improvements to the documentation structure and clarity regarding file purposes and workflows. **Copilot and Agent Instruction Enhancements:** - Added a new `.github/copilot-instructions.md` file providing detailed, repository-wide setup, build, CI/CD, troubleshooting, and file format guidance for Copilot coding agents. - Introduced `.github/instructions/bibtex-bibliography.instructions.md` with specific instructions for editing and validating BibTeX files, including custom keywords, formatting rules, and integration with Jekyll-Scholar. - Updated agent documentation files (`customize.agent.md`, `docs.agent.md`) to reference the new Copilot instruction files and explain their purpose and usage for both repository-wide and path-specific scenarios. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L107-R122) [[3]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51) [[4]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137) **Documentation Structure and Clarity Improvements:** - Clarified and reorganized the documentation file list in agent files, removing references to deprecated or merged files (e.g., `MAINTENANCE.md`, `ACCESSIBILITY.md`) and updating descriptions to reflect current usage. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L21-R21) [[3]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137) - Enhanced documentation on the purpose and application of each documentation file, and added detailed explanations of Copilot instruction files and their role in project development. **Workflow and Validation Updates:** - Updated references and descriptions for GitHub Actions workflows in agent documentation to include the Copilot environment setup and clarify pre-commit and CI/CD requirements. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51) - Corrected references for accessibility guidance, now directing users to `TROUBLESHOOTING.md` instead of the removed `ACCESSIBILITY.md`. These changes collectively improve the onboarding experience for both human contributors and AI agents, ensuring consistent adherence to project conventions and reducing errors. **References:** [[1]](diffhunk://#diff-227c2c26cb2ee0ce0f46a320fc48fbcbdf21801a57f59161b1d0861e8aad55f5R1-R253) [[2]](diffhunk://#diff-6fd2827fb8d9c2dd6dc973572201853487ecbbd1120b00425d4f1c21dfdcf35fR1-R174) [[3]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[4]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L107-R122) [[5]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L550-R562) [[6]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L21-R21) [[7]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51) [[8]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137) --------- Signed-off-by: George Araújo <george.gcac@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
95 lines
6.2 KiB
Markdown
95 lines
6.2 KiB
Markdown
# Contributing to al-folio
|
||
|
||
Thank you for considering contributing to al-folio!
|
||
|
||
## Pull Requests
|
||
|
||
We welcome your pull requests (PRs).
|
||
For minor fixes (e.g., documentation improvements), feel free to submit a PR directly.
|
||
If you would like to implement a new feature or a bug, please make sure you (or someone else) has opened an appropriate issue first; in your PR, please mention the issue it addresses.
|
||
|
||
Note that since [#2048](https://github.com/alshedivat/al-folio/pull/2048) al-folio uses the [prettier formatter](https://prettier.io/) for its code, meaning all new submitted code must conform to its standard. If you don't have `prettier` installed for your setup and the `prettier` code check fails when submitting a PR, you can check the referred failed action in our repo. In that action there will be an artifact with an HTML diff showing the needed changes.
|
||
|
||
## GitHub Copilot Agents
|
||
|
||
This repository includes two specialized GitHub Copilot agents to assist with development and documentation:
|
||
|
||
### Customization Agent
|
||
|
||
The **Customization Agent** (`.github/agents/customize.agent.md`) helps users customize their al-folio website. It:
|
||
|
||
- Guides you through modifying configuration files, adding content, and customizing the theme
|
||
- Explains technical concepts in plain language for users without coding experience
|
||
- Applies changes directly to your repository files
|
||
- Provides step-by-step instructions for common customization tasks
|
||
|
||
To use the customization agent, you need to have [GitHub Copilot](https://github.com/features/copilot) enabled in your repository. The agent can help with tasks like changing site information, updating your CV, adding publications, creating blog posts, customizing theme colors, and more.
|
||
|
||
### Documentation Agent
|
||
|
||
The **Documentation Agent** (`.github/agents/docs.agent.md`) maintains the project documentation. It:
|
||
|
||
- Updates and maintains documentation files (`README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`)
|
||
- Keeps documentation in sync with code changes
|
||
- Writes clear, concise documentation for users without technical backgrounds
|
||
- Follows documentation standards and best practices
|
||
|
||
The documentation agent is primarily intended for maintainers and contributors who are updating the project documentation.
|
||
|
||
### Custom Instruction Files
|
||
|
||
To enhance GitHub Copilot's effectiveness when working with specific file types, this repository includes custom instruction files in `.github/instructions/`:
|
||
|
||
- **`.github/copilot-instructions.md`** – Main Copilot instructions with repository overview, build process, tech stack, project layout, CI/CD pipelines, and common pitfalls
|
||
- **`.github/instructions/liquid-templates.instructions.md`** – Guidance for modifying Liquid template files (`.liquid`)
|
||
- **`.github/instructions/yaml-configuration.instructions.md`** – Guidance for configuration and data files (`_config.yml`, `_data/**/*.yml`)
|
||
- **`.github/instructions/bibtex-bibliography.instructions.md`** – Guidance for bibliography files (`.bib`, `_bibliography/**`)
|
||
- **`.github/instructions/markdown-content.instructions.md`** – Guidance for content files across collections (`_books/`, `_news/`, `_pages/`, `_posts/`, `_projects/`, `_teachings/`)
|
||
- **`.github/instructions/javascript-scripts.instructions.md`** – Guidance for JavaScript files in `_scripts/`
|
||
|
||
These files help Copilot agents understand project conventions, build requirements, and development workflows without requiring codebase exploration.
|
||
|
||
### Copilot Environment Setup
|
||
|
||
A GitHub Actions workflow (`.github/workflows/copilot-setup-steps.yml`) automatically configures the Copilot environment with required dependencies (Ruby 3.3.5, Python 3.13, Node.js, ImageMagick, nbconvert) before agent execution.
|
||
|
||
### Important: Verify Agent Output
|
||
|
||
While these agents are designed to assist you, **they can make mistakes or produce incorrect information**. Always review and verify the output before applying it to your repository:
|
||
|
||
- **Review code and configuration changes** – Check that suggested modifications are correct and fit your needs
|
||
- **Test changes locally** – Before pushing to GitHub, test the changes locally (using Docker or native setup)
|
||
- **Verify syntax** – Ensure any YAML, Markdown, or configuration files have correct syntax
|
||
- **Check documentation** – If the agent generates documentation, review it for accuracy and clarity
|
||
- **Don't blindly apply changes** – Understand what changes are being made and why
|
||
- **Run your site** – After applying changes, run your site locally and verify everything works as expected
|
||
|
||
**Example:** If an agent suggests a BibTeX entry or configuration change, verify that the syntax is correct and matches the existing style in your repository before committing.
|
||
|
||
### How to Enable Agents
|
||
|
||
GitHub Copilot agents are available to users with GitHub Copilot subscriptions. To use these agents:
|
||
|
||
1. Ensure you have [GitHub Copilot](https://github.com/features/copilot) enabled for your account
|
||
2. Open your repository in an editor with GitHub Copilot support (such as VS Code with the GitHub Copilot extension)
|
||
3. The agents will be automatically available based on the configuration files in `.github/agents/`. For more information, see [Using custom agents in your IDE](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents#using-custom-agents-in-your-ide).
|
||
|
||
For more information about GitHub Copilot agents and how to use them, see the [GitHub Copilot documentation](https://docs.github.com/en/copilot).
|
||
|
||
## Issues
|
||
|
||
We use GitHub issues to track bugs and feature requests.
|
||
Before submitting an issue, please make sure:
|
||
|
||
1. You have read [the FAQ section](FAQ.md) of the README and your question is NOT addressed there.
|
||
2. You have done your best to ensure that your issue is NOT a duplicate of one of [the previous issues](https://github.com/alshedivat/al-folio/issues).
|
||
3. Your issue is either a bug (unexpected/undesirable behavior) or a feature request.
|
||
If it is just a question, please ask it in the [Discussions](https://github.com/alshedivat/al-folio/discussions) forum.
|
||
|
||
When submitting an issue, please make sure to use the appropriate template.
|
||
|
||
## License
|
||
|
||
By contributing to al-folio, you agree that your contributions will be licensed
|
||
under the LICENSE file in the root directory of the source tree.
|