[NOTICKET] Update and enrich agent instructions by Copilot · Pull Request #1018 · ecosia/ios-browser

Copilot · 2026-02-07T18:40:54Z

Rewrites .github/copilot-instructions.md from sparse notes into structured, scannable guidance for AI coding agents.

Added

Architecture overview — directory map (firefox-ios/Ecosia/ framework vs firefox-ios/Client/Ecosia/ legacy vs Firefox core), core module index (Analytics/Snowplow, Experiments/Unleash, Braze, UI)
Extension pattern — documents the +Ecosia convention for customizing Firefox classes without modifying originals
Environment detection — bundle ID → environment mapping
Build & dev workflow — bootstrap → Xcode scheme selection → SwiftLint → webpack user scripts → test scheme (EcosiaBeta) → CI (Bitrise + GitHub Actions)
File header requirement — MPL-2.0 enforced by SwiftLint file_header rule
Testing conventions — snapshot testing via SnapshotTestHelper, Analytics.shared reassignment guard, mocks location
Translations — added ecosify-strings.py rebranding step for upstream merges

Preserved

All original content (commenting guidelines, user scripts, PR naming, ADRs, translations, snapshot testing, documentation policies) — restructured with real code examples from the codebase.

Original prompt

This section details on the original issue you should resolve

<issue_title>update agent instructions</issue_title>
<issue_description>Analyze this codebase to generate or update .github/copilot-instructions.md for guiding AI coding agents.

Focus on discovering the essential knowledge that would help an AI agents be immediately productive in this codebase. Consider aspects like:

The "big picture" architecture that requires reading multiple files to understand - major components, service boundaries, data flows, and the "why" behind structural decisions

Critical developer workflows (builds, tests, debugging) especially commands that aren't obvious from file inspection alone

Project-specific conventions and patterns that differ from common practices

Integration points, external dependencies, and cross-component communication patterns

Source existing AI conventions from **/{.github/copilot-instructions.md,AGENT.md,AGENTS.md,CLAUDE.md,.cursorrules,.windsurfrules,.clinerules,.cursor/rules/**,.windsurf/rules/**,.clinerules/**,README.md} (do one glob search).

Guidelines (read more at https://aka.ms/vscode-instructions-docs):

If .github/copilot-instructions.md exists, merge intelligently - preserve valuable content while updating outdated sections

Write concise, actionable instructions (~20-50 lines) using markdown structure

Include specific examples from the codebase when describing patterns

Avoid generic advice ("write tests", "handle errors") - focus on THIS project's specific approaches

Document only discoverable patterns, not aspirational practices

Reference key files/directories that exemplify important patterns

Update .github/copilot-instructions.md for the user, then ask for feedback on any unclear or incomplete sections to iterate.</issue_description>

<agent_instructions>update and enrich the currenct agent instructions</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes update agent instructions #1017

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

…ve agent guidance Co-authored-by: falkorichter <50506+falkorichter@users.noreply.github.com>

falkorichter · 2026-02-07T18:52:47Z

@@ -1,70 +1,108 @@
-always consider this codebase is mixed with firefox-ios and our modifications


@copilot keep these instructions in a separate secion

Copilot

Pull request overview

Updates the repository’s Copilot/agent guidance by rewriting .github/copilot-instructions.md into a structured set of instructions that explains the Ecosia-vs-Firefox fork architecture, common customization patterns, and key developer workflows.

Changes:

Adds an architecture overview (directory map + key Ecosia modules) and documents the +Ecosia extension pattern.
Documents environment detection (bundle ID mapping) and expands build/dev workflow guidance (bootstrap, SwiftLint, webpack user scripts, test scheme, CI).
Adds/organizes guidance on MPL file headers, testing conventions, translations, PR naming, ADRs, and documentation policies.

Copilot · 2026-02-07T18:59:15Z

+## Build & Development

-when adding or editing User Scripts in `/Client/Frontend/UserContent/UserScripts/`, recompile them by running `npm run build` in the project root
+1. **Bootstrap**: `sh ./bootstrap.sh` (installs hooks, resolves packages, updates content blockers, creates `Staging.xcconfig`)


The bootstrap step claims ./bootstrap.sh "resolves packages", but the script currently only installs git hooks, updates the content blocker, downloads Nimbus tooling, and creates Staging.xcconfig. Please remove or reword the "resolves packages" part to match what the script actually does.

Suggested change

1. **Bootstrap**: `sh ./bootstrap.sh` (installs hooks, resolves packages, updates content blockers, creates `Staging.xcconfig`)

1. **Bootstrap**: `sh ./bootstrap.sh` (installs git hooks, updates the content blocker, downloads Nimbus tooling, creates `Staging.xcconfig`)

Copilot · 2026-02-07T18:59:16Z

+   - Output: `firefox-ios/Client/Assets/` (`AllFramesAtDocumentEnd.js`, etc.)
+   - Rebuild: `npm run build` from the project root


The User Scripts section lists outputs under firefox-ios/Client/Assets/ (e.g. AllFramesAtDocumentEnd.js). Those files are .gitignore'd in this repo, so agents may be confused when they don't appear in git status / PRs. Suggest explicitly noting that these are generated build artifacts (ignored by git) and will be produced locally after npm run build.

Suggested change

- Output: `firefox-ios/Client/Assets/` (`AllFramesAtDocumentEnd.js`, etc.)

- Rebuild: `npm run build` from the project root

- Output: `firefox-ios/Client/Assets/` (`AllFramesAtDocumentEnd.js`, etc.) — these are generated build artifacts, ignored by git in this repo.

- Rebuild: `npm run build` from the project root (this will generate/update the user script assets under `firefox-ios/Client/Assets/` locally)

Copilot · 2026-02-07T18:59:16Z

+# Ecosia iOS Browser — Copilot Instructions

-write comprehensive tests
+## Architecture Overview

-keep `firefox-ios/Ecosia/Ecosia.docc/Ecosia.md` up to date
+This is a **fork of Mozilla Firefox iOS** with Ecosia-specific customizations layered on top. Code changes touch both Firefox core files and Ecosia-owned modules. Always consider this dual-origin when making changes — minimize modifications to Firefox core to reduce upstream merge conflicts.



The original prompt included in the PR description recommends keeping Copilot instructions concise (~20–50 lines), but the updated file is ~109 lines. Consider trimming/merging sections (or moving deep details into firefox-ios/Ecosia/Ecosia.docc/Ecosia.md) to keep this file scannable and aligned with the stated guidance.

Copilot · 2026-02-07T18:59:16Z

+| Path | Purpose |
+|---|---|
+| `firefox-ios/Ecosia/` | **Ecosia Framework** — isolated Ecosia logic (analytics, core models, networking, experiments, UI components). New Ecosia code goes here. |
+| `firefox-ios/Client/Ecosia/` | Ecosia code within the Client target (extensions on Firefox classes, NTP, settings, onboarding). Legacy location — prefer the framework when possible. |
+| `firefox-ios/Client/` | Firefox Client app — Ecosia modifications are marked with `// Ecosia:` comments. |
+| `firefox-ios/EcosiaTests/` | Ecosia unit tests and snapshot tests. |
+| `BrowserKit/` | Shared Swift package (Common, Redux, SiteImageView, TabDataStore, WebEngine, etc.). |


The markdown table under "Key Directories" has an extra leading pipe (||) on each row, which will render as an empty first column / malformed table in most Markdown renderers. Use a single leading | per row so the table renders correctly.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

lucaschifino

Great initiative to get this started, thank you!

It's already a big improvement just to have this and I have no big blockers. I'm challenging the structure now early so we can have a better baseline moving forward - happy to jump further into discussions or maybe iterate over this in other PRs as we try out things 🙂

lucaschifino · 2026-02-09T15:19:56Z

+| Path | Purpose |
+|---|---|
+| `firefox-ios/Ecosia/` | **Ecosia Framework** — isolated Ecosia logic (analytics, core models, networking, experiments, UI components). New Ecosia code goes here. |
+| `firefox-ios/Client/Ecosia/` | Ecosia code within the Client target (extensions on Firefox classes, NTP, settings, onboarding). Legacy location — prefer the framework when possible. |


Might be good to mention Ecosia code that heavily depends on Firefox Client code needs to still be here, but great to mention framework should be preferred 🙂

let's propose some changes, we can work on this as a team

there is a mention of the firefox forking

lucaschifino · 2026-02-09T15:23:31Z

+### Core Ecosia Modules (inside `firefox-ios/Ecosia/`)

-consider a architecture decision record based on this template
-https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/locales/en/templates/decision-record-template-of-the-madr-project is a good template
-request other considerations needed to implement a feature
-document unsolved issues in the architecture decision record
-ADRs should be stored in `docs/decisions/` and the readme `docs/decisions/README.md` should be updated to have an up-to-date list
-`docs/decisions/0001-swiftlint-configuration-for-upstream-fork.md` is a good name for the ADR
+- **Core/** — `User`, `Environment`, `HTTPClient`, `Statistics`, `Referrals`, `SearchesCounter`, `Navigation`
+- **Analytics/** — Snowplow-based analytics via `Analytics.shared` (do not reassign outside tests — enforced by SwiftLint)
+- **Experiments/Unleash/** — Feature flags via Unleash (`Unleash.start(..., appVersion:)`)
+- **Braze/** — Push notification integration (`BrazeService`)
+- **UI/** — SwiftUI/UIKit design system, NTP components, settings, onboarding


This structure might not be the best, it's still a bit of a legacy and intermediary state from moving out of the private ios-core (inside Core folder) and still using Client namings like UI folder.

Not urgent, but maybe a nice nudge to re-discuss and organise it?

For now maybe we want to leave out from this doc since it might be easily deprecated anyway?

lucaschifino · 2026-02-09T15:53:29Z

+This makes upstream merges easier — the original Firefox code is visible inside the block comment.

-User Scripts (JavaScript injected into WKWebView) are compiled, concatenated, and minified using webpack
+## Build & Development


Can't agents get this build information from our Readme? I think that would be better for maintainability and not repeating ourselves.

lucaschifino · 2026-02-09T15:54:39Z

-## Snapshot Testing
+- PR title: `[MOB-XXXX] {name of the feature}` (ticket reference from Jira)
+- Branch name must include `MOB-XXXX` (e.g., `mob-1234/feature-name`)
+- No ticket? Use `NOTICKET` in PR title and `noticket` in branch name


Is this something we want? To be honest just not having the [MOB-XXXX] part is enough imo and more clean. What advantages do you see from this?

lucaschifino · 2026-02-09T15:56:30Z

+## Architecture Decision Records (ADRs)

-snapshot tests support multiple themes, devices, and localizations
+- Store in `docs/decisions/` using MADR format
+- Naming: `NNNN-short-title.md` (e.g., `0001-swiftlint-configuration-for-upstream-fork.md`)
+- Update `docs/decisions/README.md` index when adding new ADRs
+- Document unsolved issues and considered alternatives


Links to discussion on other PR (#1016 (comment)), but I think for the sake of simplicity it would be best if we own ADRs, not AI, otherwise I feel they would create this often for changes that do not need a decision per se.

Might also be this saves time and we can better limit it though, we can try some things.

I write my own ADRs - you write your own ADRs, if we have a tool that helps us write them, we are better engineers. It doesn't hurt to have it propose something. That's the general direction I'm following.

Same for tests

Same for the code

We own the PR.

Many of the code has more thinking behind it which can be documented in ADR-like files.

lucaschifino · 2026-02-09T15:57:32Z

+## Documentation

-see `SNAPSHOT_TESTING_WIKI.md` for more details
+- Keep `firefox-ios/Ecosia/Ecosia.docc/Ecosia.md` up to date with architecture changes


In my experience AI often adds stuff to the Readme on minor changes, even unprompted, so I wonder if adding this to instructions won't result in more clutter on our Readme?

Similar response here - if we want the readme to be up to date, we need to keep it up to date, we need to tell the same to the tools we're using.

I have amazing experiences with the readme being kept up to date all the time and using the neccesary resources. I was doing this manually, I also accept good help 💪

lucaschifino · 2026-02-09T15:59:21Z

I believe Copilot can already use Agents.md, can it not? Maybe we should already use that as a more general solution.

lucaschifino · 2026-02-09T16:01:59Z

More of a general comment, but I myself have had more luck with limiting the instructions given to the AI to the minimum, otherwise it gets lost trying to do too much.

We've discussed this in the company too and an approach similar to the Core repo Agents.md file might work best, giving more behaviour context and having more localised code instructions to reduce the amount of unnecessary context depending on the change.

Do you have any other experience? What do you think of the different approaches?

This file has served me well so far, we can also rename it to agents.md but I didn't want to interfere with other work.

In terms of size, the context window is growing with the models - context is king.

lucaschifino

No blockers to merge this in and iterate on demand

* [NOTICKET] Update and enrich copilot-instructions.md with comprehensive agent guidance

…1030) * [NOTICKET] Update and enrich agent instructions (#1018) * [NOTICKET] Update and enrich copilot-instructions.md with comprehensive agent guidance * brought back the swift baseline Added instructions for updating the swiftlint baseline and maintaining code quality. * added an ADR swiftlint --fix firefox-ios/Client/Ecosia/Telemetry/FakeGleanWrapper.swift worked, but the output of the baseline is not uniform * Add 'develop' branch to SwiftLint workflow --------- Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: Falko Richter <falko.richter@ecosia.org> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Initial plan

60dba96

Copilot AI assigned Copilot and falkorichter Feb 7, 2026

Copilot started work on behalf of falkorichter February 7, 2026 18:41 View session

[NOTICKET] Update and enrich copilot-instructions.md with comprehensi…

e39ba77

…ve agent guidance Co-authored-by: falkorichter <50506+falkorichter@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Update agent instructions for AI coding agents~~ [NOTICKET] Update and enrich agent instructions Feb 7, 2026

Copilot AI requested a review from falkorichter February 7, 2026 18:45

Copilot finished work on behalf of falkorichter February 7, 2026 18:45

falkorichter reviewed Feb 7, 2026

View reviewed changes

Copilot started work on behalf of falkorichter February 7, 2026 18:53 View session

Copilot AI requested a review from falkorichter February 7, 2026 18:53

Copilot stopped work on behalf of falkorichter due to an error February 7, 2026 18:53
The session was cancelled by the user.

falkorichter marked this pull request as ready for review February 7, 2026 18:54

falkorichter requested review from a team and Copilot February 7, 2026 18:54

Copilot started reviewing on behalf of falkorichter February 7, 2026 18:54 View session

Copilot AI reviewed Feb 7, 2026

View reviewed changes

Update .github/copilot-instructions.md

15d0c43

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

lucaschifino reviewed Feb 9, 2026

View reviewed changes

lucaschifino approved these changes Feb 10, 2026

View reviewed changes

falkorichter merged commit 62c4d1b into main Feb 10, 2026
2 of 3 checks passed

falkorichter deleted the copilot/update-copilot-instructions branch February 10, 2026 11:11

falkorichter pushed a commit that referenced this pull request Feb 10, 2026

[NOTICKET] Update and enrich agent instructions (#1018)

9c5e47a

* [NOTICKET] Update and enrich copilot-instructions.md with comprehensive agent guidance

falkorichter mentioned this pull request Feb 10, 2026

Noticket cherry picked update copilot instructions and swiftlint #1030

Merged

		@@ -1,70 +1,108 @@
		always consider this codebase is mixed with firefox-ios and our modifications

	1. Bootstrap: `sh ./bootstrap.sh` (installs hooks, resolves packages, updates content blockers, creates `Staging.xcconfig`)
	1. Bootstrap: `sh ./bootstrap.sh` (installs git hooks, updates the content blocker, downloads Nimbus tooling, creates `Staging.xcconfig`)

		- Output: `firefox-ios/Client/Assets/` (`AllFramesAtDocumentEnd.js`, etc.)
		- Rebuild: `npm run build` from the project root

Conversation

Copilot AI commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Added

Preserved

Comments on the Issue (you are @copilot in this section)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lucaschifino left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucaschifino left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Feb 7, 2026 •

edited

Loading