Kirim manifes Anda ke repositori

Setelah membuat manifes paket yang menjelaskan aplikasi, Anda siap untuk mengirimkan manifes ke repositori Pengelola Paket Windows. Ini adalah repositori yang menghadap publik yang berisi kumpulan manifes yang dapat diakses alat winget . Untuk mengirimkan manifes, Anda akan mengunggahnya ke repositori sumber terbuka https://github.com/microsoft/winget-pkgs di GitHub.

Setelah Anda mengirimkan permintaan tarik untuk menambahkan manifes baru ke repositori GitHub, proses otomatis akan memvalidasi file manifes Anda dan memeriksa serta memastikan paket mematuhi kebijakan Pengelola Paket Windows dan tidak dianggap berbahaya. Jika validasi ini berhasil, paket Anda akan ditambahkan ke repositori Pengelola Paket Windows yang menghadap publik sehingga dapat ditemukan oleh alat klien winget. Perhatikan perbedaan antara manifes di repositori GitHub sumber terbuka dan repositori Pengelola Paket Windows yang menghadap publik.

Penting

Microsoft berhak menolak pengiriman karena alasan apa pun.

Validasi manifes

Ketika Anda mengirimkan manifes ke https://github.com/microsoft/winget-pkgs repositori di GitHub, manifes Anda akan secara otomatis divalidasi dan dievaluasi untuk keamanan ekosistem Windows. Manifes juga dapat ditinjau secara manual.

Untuk informasi selengkapnya tentang proses validasi, lihat bagian proses validasi di bawah ini.

Cara menyerahkan dokumen manifes Anda

Untuk mengirimkan manifes ke repositori, ikuti langkah-langkah berikut.

Langkah 1: Validasi manifes Anda

Alat winget menyediakan perintah validasi untuk mengonfirmasi bahwa Anda telah membuat manifes dengan benar. Untuk memvalidasi manifes Anda, gunakan perintah ini.

winget validate \<path-to-the-manifests>

Jika validasi Anda gagal, gunakan kesalahan untuk menemukan nomor baris dan membuat koreksi. Setelah manifes telah divalidasi, Anda dapat mengirimkannya ke repositori.

Langkah 2: Uji manifes Anda dengan Kotak Pasir Windows

Repositori Pengelola Paket Windows menyertakan skrip yang akan menginstal Pengelola Paket Windows di Sandbox untuk menguji pengiriman manifes. Untuk menjalankan skrip powershell, navigasikan ke repositori winget-pkgs Anda. Dari PowerShell, masukkan perintah berikut:

powershell .\Tools\SandboxTest.ps1 manifests\m\Microsoft\VisualStudioCode\1.56.0

Anda mungkin perlu memperbarui skrip ini dengan jalur yang benar ke file manifes Anda: .\Tools\SandboxTest.ps1 <path to manifest or manifest folder>

Lihat skrip pengujian kotak pasir lengkap di repositori winget-pkgs.

Langkah 3: Kloning repositori

Untuk membuat fork repositori Komunitas Pengelola Paket Windows dan mengkloning repositori ke komputer lokal Anda:

1. Buka https://github.com/microsoft/winget-pkgs di browser Anda dan pilih Fork.

2. Dari Windows Command Prompt atau PowerShell, gunakan perintah berikut untuk mengkloning fork Anda.

   git clone --filter=blob:none --no-checkout <your-fork-name>
   

Langkah 4: Menyiapkan sparse checkout

Sparse checkout memungkinkan memilih bagian repositori yang ingin diunduh, bukan mengunduh semuanya. Pada langkah sebelumnya, --filter=blob:none berarti bahwa riwayat penerapan belum diunduh, dan --no-checkout berarti bahwa belum ada file yang ditambahkan ke salinan kerja (indeks).

Sebelum mengunduh apa pun, Anda harus menentukan filter untuk checkout selektif yang akan digunakan (disimpan di .git/info/sparse-checkout).

Pertama, berikut adalah penjelasan tentang apa yang akan disiapkan. Anda harus menambahkan file manifes ke repositori dalam struktur folder berikut:

manifes / surat / penerbit / aplikasi / versi

• Folder manifes adalah folder akar untuk semua manifes di repositori.
• Folder huruf adalah huruf pertama dari nama penerbit dalam huruf kecil. Misalnya, m penerbit Microsoft.
• Folder penerbit adalah nama perusahaan yang menerbitkan perangkat lunak. Misalnya, Microsoft.
• Folder aplikasi adalah nama aplikasi atau alat. Misalnya, VSCode.
• Folder versi adalah versi aplikasi atau alat. Misalnya, 1.0.0.

PackageIdentifier dan PackageVersion nilai dalam manifes harus cocok dengan penerbit, nama aplikasi, dan versi di jalur folder manifes. Untuk informasi selengkapnya, lihat Buat manifes paket Anda.

Untuk itu, untuk menyiapkan checkout parsial untuk semua file konfigurasi penerbit, Anda akan mengetik:

• Jika Anda menggunakan Git versi 2.37.0 atau yang lebih baru, jalankan perintah berikut untuk menyiapkan sparse checkout pada folder Anda.

  git sparse-checkout set manifests\<letter>\<publisher>
  

• Jika Anda menggunakan versi Git yang lebih lama, lihat dokumentasi Git tentang cara menyiapkan cek keluar jarang untuk repositori lokal Anda.

Perhatikan bahwa perintah di atas akan mengganti semua pengaturan checkout selektif saat ini dan mengaturnya hanya untuk folder tersebut. Lihat dokumentasi Git untuk menyiapkan checkout selektif dengan beberapa folder.

Langkah 5: Lihat repositori

Anda sekarang dapat menerapkan pengaturan checkout sparse dengan menjalankan perintah checkout normal.

git checkout

Bahkan jika folder yang ingin Anda submit belum di-commit ke repositori, Anda tetap harus menjalankan perintah checkout, karena tidak mungkin untuk menambahkan (dan dengan demikian di-commit) apa pun tanpa internal Git yang disetelnya (indeks).

Jika Anda mengajukan beberapa komitmen, buat cabang daripada membuat fork. Saat ini kami hanya mengizinkan satu file manifes per pengiriman.

git checkout -b <branch-name>

Langkah 6: Tambahkan manifes Anda ke repositori lokal

Tambahkan file Anda ke folder berikut (format yang dijelaskan di langkah 4): manifes / surat / penerbit / aplikasi / versi

Langkah 7: Kirim manifes Anda ke repositori jarak jauh

Anda siap mengunggah manifes baru Anda ke repositori jarak jauh.

1. commit Gunakan perintah untuk menambahkan file dan menerapkan perubahan dan memberikan informasi tentang pengiriman.

   git commit -m "Submitting ContosoApp version 1.0.0" --all
   

2. push Gunakan perintah untuk mendorong perubahan ke repositori jarak jauh.

   git push
   

Langkah 8: Membuat pull request

Setelah Anda melakukan push perubahan Anda, kembali ke https://github.com/microsoft/winget-pkgs dan buat pull request untuk menggabungkan fork atau cabang Anda ke cabang utama.

Proses pengiriman

Saat Anda membuat permintaan pull, ini akan memulai proses otomatis yang memvalidasi manifes dan memverifikasi permintaan pull Anda. Selama proses ini, kami akan menjalankan pengujian terhadap alat penginstal dan biner yang diinstal untuk memvalidasi pengiriman.

Kami menambahkan label ke permintaan pull Anda sehingga Anda dapat melacak kemajuannya. Untuk informasi selengkapnya tentang label dan prosesnya, lihat bagian label permintaan tarik di bawah ini.

Setelah selesai, pengiriman Anda akan ditinjau secara manual oleh moderator, dan setelah disetujui, aplikasi Anda akan ditambahkan ke katalog Pengelola Paket Windows.

Jika ada kesalahan selama proses, Anda akan diberi tahu dan label dan bot kami akan membantu Anda dalam memperbaiki pengiriman Anda. Untuk daftar kesalahan umum, lihat bagian proses validasi di bawah ini.

Proses validasi

Saat Anda membuat permintaan pull untuk mengirimkan manifes Anda ke repositori Pengelola Paket Windows, ini akan memulai proses otomatisasi yang memvalidasi manifes dan memproses permintaan pull Anda. Label GitHub digunakan untuk berbagi kemajuan dan memungkinkan Anda berkomunikasi dengan kami.

Ekspektasi pengiriman

Semua pengiriman aplikasi ke repositori Pengelola Paket Windows harus mematuhi kebijakan repositori Pengelola Paket Windows.

Harapan untuk pengajuan:

• Manifes mematuhi persyaratan skema.
• Semua URL dalam manifes mengarah ke situs web yang aman.
• Alat penginstal dan aplikasi bebas virus. Paket dapat diidentifikasi sebagai malware secara tidak sengaja. Jika Anda yakin itu adalah positif palsu, Anda dapat mengirimkan alat penginstal ke tim Pertahanan Microsoft untuk dianalisis.
• Aplikasi menginstal dan menghapus instalasi dengan benar untuk administrator dan non-administrator.
• Alat penginstal mendukung mode non-interaktif.
• Semua entri manifes akurat dan tidak menyesatkan.
• Alat penginstal berasal langsung dari situs web penerbit.

Untuk daftar lengkap kebijakan, lihat kebijakan Pengelola Paket Windows.

Label permintaan pull

Selama validasi, serangkaian label diterapkan pada pull request (permintaan tarik) untuk mengomunikasikan kemajuan. Beberapa label akan mengarahkan Anda untuk mengambil tindakan, sementara yang lain akan diarahkan ke tim teknik Pengelola Paket Windows.

Label status

Tabel berikut ini menjelaskan label status yang mungkin Anda temui.

Label	Rincian
Azure-Pipeline-Lulus	Manifest telah menyelesaikan tahap pengujian. Ini menunggu persetujuan. Jika tidak ada masalah yang ditemui selama lulus pengujian, itu akan secara otomatis disetujui. Jika pengujian gagal, hal tersebut bisa diindikasikan untuk peninjauan manual.
Masalah Pemblokiran	Label ini menunjukkan bahwa permintaan pull tidak dapat disetujui karena ada masalah pemblokiran. Anda sering dapat mengetahui masalah pemblokiran dari label kesalahan yang disertakan.
Butuh Perhatian	Label ini menunjukkan bahwa permintaan pull perlu diselidiki oleh tim pengembangan Pengelola Paket Windows. Hal ini disebabkan oleh kegagalan pengujian yang memerlukan peninjauan manual, atau komentar yang ditambahkan ke permintaan pull oleh komunitas.
Perlu-Penulis-Umpan Balik	Menunjukkan bahwa terdapat kegagalan dalam pengiriman. Kami akan menetapkan ulang pull request kembali kepada Anda. Jika Anda tidak mengatasi masalah dalam waktu 10 hari, bot akan menutup permintaan pull. Label Needs-Author-Feedback biasanya ditambahkan ketika terjadi kegagalan dengan pull request yang harus diperbarui, atau jika orang yang meninjau pull request memiliki pertanyaan.
Validasi Selesai	Menunjukkan bahwa uji coba telah berhasil selesai dan permintaan tarik Anda akan digabung.

Kesalahan label

Tabel berikut ini menjelaskan label kesalahan yang mungkin Anda temui. Tidak semua kasus kesalahan akan diberikan kepada Anda segera. Beberapa mungkin memicu validasi manual.

Label	Rincian
Binary-Validation-Error	Aplikasi yang disertakan dalam permintaan pull ini gagal lulus uji Pemindaian Penginstal . Pengujian ini dirancang untuk memastikan bahwa aplikasi diinstal pada semua lingkungan tanpa peringatan. Untuk detail selengkapnya tentang kesalahan ini, lihat bagian Kesalahan validasi biner di bawah ini.
Batas Waktu Analisis Kesalahan	Tes Binary-Validation-Test berakhir karena batas waktu. Permintaan pull akan diteruskan kepada teknisi Pengelola Paket Windows untuk menyelidikinya.
Kesalahan Ketidakcocokan Hash	Manifes yang dikirimkan tidak dapat diproses karena hash InstallerSha256 yang disediakan untuk InstallerURL tidak cocok. Perbarui InstallerSha256 dalam permintaan pull dan coba lagi.
Ketersediaan-Penginstal-Error	Layanan validasi tidak dapat mengunduh alat penginstal. Ini mungkin terkait dengan rentang IP Azure yang diblokir, atau URL penginstal mungkin salah. Periksa apakah InstallerURL sudah benar dan coba lagi. Jika Anda merasa ini gagal karena ada kesalahan, tambahkan komentar dan permintaan tarik akan ditetapkan ke teknisi Pengelola Paket Windows untuk diselidiki.
Manifest-Installer-Validation-Error	Ada inkonsistensi atau nilai yang tidak ada dalam manifes selama evaluasi paket MSIX.
Kesalahan Jalur Manifes	File manifes harus dimasukkan ke dalam struktur folder tertentu. Label ini menunjukkan masalah dengan jalur pengiriman Anda. Misalnya, struktur folder tidak memiliki format yang diperlukan. Perbarui manifes Anda dan kirim ulang permintaan tarik Anda.
Manifest-Validation-Error	Manifes yang dikirimkan berisi kesalahan sintaksis. Atasi masalah sintaksis dengan manifes dan kirim ulang. Untuk detail tentang format dan skema manifes, lihat format yang diperlukan.
PullRequest-Error	Permintaan pull tidak valid karena tidak semua file yang dikirimkan berada di bawah folder manifes atau ada lebih dari satu paket atau versi dalam permintaan pull. Perbarui permintaan pull Anda untuk mengatasi masalah ini, lalu coba lagi.
Kesalahan-Validasi-URL	Pengujian Validasi URL tidak dapat menemukan URL dan merespons dengan kode status kesalahan HTTP (403 atau 404), atau pengujian reputasi URL gagal. Anda dapat mengidentifikasi URL mana yang dimaksud dengan melihat detail pemeriksaan pull request. Untuk mengatasi masalah ini, perbarui URL yang dimaksud untuk mengatasi kode status kesalahan HTTP. Jika masalah ini bukan karena kode status kesalahan HTTP, Anda dapat mengirimkan URL untuk ditinjau guna menghindari kegagalan reputasi.
Validasi-Defender-Error	Selama pengujian dinamis, Microsoft Defender melaporkan sebuah masalah. Untuk mereprodurasi masalah ini, instal aplikasi Anda, lalu jalankan pemindaian penuh Pertahanan Microsoft. Jika Anda dapat mereprodusi masalah, perbaiki biner atau kirimkan untuk analisis untuk bantuan positif palsu. Jika Anda tidak dapat mereproduksi masalah, tambahkan komentar agar teknisi Pengelola Paket Windows menyelidiki.
Validasi-Domain	Pengujian telah menentukan domain jika InstallerURL tidak cocok dengan domain yang diharapkan. Kebijakan Pengelola Paket Windows mengharuskan InstallerUrl berasal langsung dari lokasi rilis ISV. Jika Anda yakin ini adalah deteksi palsu, tambahkan komentar ke permintaan tarik agar insinyur di Pengelola Paket Windows dapat menyelidikinya.
Validasi-Kesalahan	Validasi terhadap Pengelola Paket Windows gagal saat persetujuan dilakukan secara manual. Lihat komentar yang menyertainya untuk langkah berikutnya.
Validasi-Kesalahan-Eksekusi	Selama pengujian penginstalan, pengujian tidak dapat menemukan aplikasi utama. Pastikan aplikasi diinstal dengan benar di semua platform. Jika aplikasi Anda tidak mampu menginstal sebuah aplikasi, namun masih harus disertakan dalam repositori, tambahkan komentar pada permintaan penarikan agar tindakan dapat diambil oleh teknisi Pengelola Paket Windows untuk menyelidiki lebih lanjut.
Validasi-Hash-Verifikasi-Gagal	Selama pengujian penginstalan, aplikasi gagal diinstal karena InstallerSha256 tidak lagi cocok dengan hash InstallerURL . Ini dapat terjadi jika aplikasi berada di belakang URL cantik dan alat penginstal diperbarui tanpa memperbarui InstallerSha256. Untuk mengatasi masalah ini, perbarui InstallerSha256 yang terkait dengan InstallerURL dan kirim lagi.
Validasi-HTTP-Kesalahan	URL yang digunakan untuk alat penginstal tidak menggunakan protokol HTTPS. Perbarui InstallerURL untuk menggunakan HTTPS dan kirim ulang Permintaan Pull.
Validasi-URL Tidak Langsung	URL tidak berasal langsung dari server ISV. Pengujian menentukan bahwa pengalih arah telah digunakan. Ini tidak diizinkan karena kebijakan Pengelola Paket Windows mengharuskan InstallerUrl berasal langsung dari lokasi rilis ISV. Hapus pengalihan dan ajukan ulang.
Validasi-Penginstalan-Kesalahan	Selama validasi manual paket ini, ada kesalahan umum. Lihat komentar yang menyertainya untuk langkah berikutnya.
Konflik Penggabungan Validasi	Paket ini tidak dapat divalidasi karena konflik penggabungan. Silakan atasi konflik penggabungan dan kirim ulang permintaan pull Anda.
Validasi-Ketergantungan-MSIX	Paket MSIX memiliki dependensi pada paket yang tidak dapat diatasi. Perbarui paket untuk menyertakan komponen yang hilang atau tambahkan dependensi ke file manifes dan kirim ulang permintaan pull.
Validasi-URL Tidak Disetujui	Pengujian telah menentukan domain jika InstallerURL tidak cocok dengan domain yang diharapkan. Kebijakan Pengelola Paket Windows mengharuskan InstallerUrl berasal langsung dari lokasi rilis ISV.
Validasi-Tanpa Pemantauan-Gagal	Selama penginstalan, waktu pengujian habis. Kemungkinan besar ini disebabkan oleh aplikasi yang tidak menginstal secara diam-diam. Ini juga bisa disebabkan oleh beberapa kesalahan lain yang ditemui dan menghentikan pengujian. Verifikasi bahwa Anda dapat menginstal manifes tanpa input pengguna. Jika Anda memerlukan bantuan, tambahkan komentar ke permintaan pull dan teknisi Pengelola Paket Windows akan menyelidikinya.
Validasi-Hapus Instalan-Kesalahan	Selama pengujian penghapusan instalasi, aplikasi tidak membersihkan sepenuhnya setelah penghapusan instalan. Lihat komentar yang menyertainya untuk detail selengkapnya.
Validasi-Ketergantungan-VCRuntime	Paket memiliki dependensi pada runtime C++ yang tidak dapat diselesaikan. Perbarui paket untuk menyertakan komponen yang hilang atau tambahkan dependensi ke file manifes dan kirim ulang permintaan pull.

Label kebijakan konten

Tabel berikut mencantumkan label kebijakan konten. Jika salah satu label ini ditambahkan, sesuatu dalam metadata manifes memicu tinjauan konten manual tambahan untuk memastikan bahwa metadata mengikuti kebijakan Pengelola Paket Windows.

Label	Rincian
Policy-Test-2.1	Lihat Persyaratan Konten Umum.
Policy-Test-2.2	Lihat Konten Termasuk Nama, Logo, Original dan Pihak Ketiga
Policy-Test-2.3	Lihat Risiko Bahaya.
Policy-Test-2.4	Lihat Pencemaran Nama Baik, Pencemaran Nama Baik secara Tertulis, Pencemaran Nama Baik secara Lisan, dan Mengancam.
Policy-Test-2.5	Lihat Konten yang Menyinggung.
Policy-Test-2.6	Lihat Alkohol, Tembakak, Senjata dan Obat-obatan.
Kebijakan-Uji-2.7	Lihat Konten Dewasa.
Uji-Kebijakan-2.8	Lihat Aktivitas Ilegal.
Policy-Test-2.9	Lihat Kata-kata Kotor yang Berlebihan dan Konten yang Tidak Pantas.
Uji-Kebijakan-2.10	Lihat Persyaratan Khusus Negara/Wilayah.
Policy-Test-2.11	Lihat Peringkat Usia.
Policy-Test-2.12	Lihat Konten yang Dihasilkan Pengguna.

Label internal

Tabel berikut mencantumkan label kesalahan internal. Ketika terjadi kesalahan internal, permintaan pencabutan Anda akan ditetapkan kepada teknisi Pengelola Paket Windows untuk menyelidiki masalah tersebut.

Label	Rincian
Internal-Error-Domain	Terjadi kesalahan selama validasi domain URL.
Kesalahan Internal-Pindai Dinamis	Terjadi kesalahan selama validasi biner yang diinstal.
Kebijakan-Kata-Kunci-Kesalahan-Internal	Terjadi kesalahan selama validasi manifes.
Manifest Kesalahan Internal	Terjadi kesalahan selama validasi manifes.
Kesalahan-Internal-TidakAdaArsitektur	Terjadi kesalahan karena pengujian tidak dapat menentukan arsitektur aplikasi.
Internal-Error-NoSupportedArchitectures	Terjadi kesalahan karena arsitektur saat ini tidak didukung.
Internal-Error-PR	Terjadi kesalahan selama pemrosesan permintaan pull.
Internal-Error-Static-Scan	Terjadi kesalahan selama analisis statis alat penginstal.
URL-Kesalahan Internal	Terjadi kesalahan saat validasi reputasi penginstal.
Kesalahan Internal	Kegagalan generik atau kesalahan yang tidak diketahui ditemui selama lulus pengujian.

Kesalahan validasi biner

Jika validasi Pull Request Anda gagal dalam pengujian Pemindaian Penginstal dan menerima label Binary-Validation-Error, berarti aplikasi Anda gagal dipasang di semua lingkungan.

Uji Pemindaian Alat Penginstal

Untuk memberikan pengalaman pengguna penginstalan aplikasi yang sangat baik, Pengelola Paket Windows harus memastikan bahwa semua aplikasi diinstal pada PC tanpa kesalahan, terlepas dari lingkungan. Salah satu pengujian utama adalah memastikan bahwa semua aplikasi diinstal tanpa peringatan pada berbagai konfigurasi antivirus populer. Windows menyediakan program antivirus Pertahanan Microsoft bawaan, tetapi banyak pelanggan perusahaan dan pengguna menggunakan perangkat lunak antivirus lainnya.

Setiap pengiriman ke Repositori Pengelola Paket Windows dijalankan melalui beberapa program antivirus. Semua program ini memiliki algoritma deteksi virus yang berbeda untuk mengidentifikasi aplikasi yang berpotensi tidak diinginkan (PUA) dan malware.

Mengatasi kesalahan validasi biner

Jika aplikasi gagal validasi, Microsoft pertama-tama mencoba memverifikasi dengan vendor antivirus apakah perangkat lunak yang ditandai adalah positif palsu. Dalam banyak kasus, setelah pemberitahuan dan validasi, vendor antivirus memperbarui algoritma mereka, dan aplikasi lolos.

Dalam beberapa kasus, vendor antivirus tidak dapat menentukan apakah anomali kode yang terdeteksi adalah positif palsu. Dalam hal ini, aplikasi tidak dapat ditambahkan ke repositori Pengelola Paket Windows. Permintaan pull ditolak dengan label Binary-Validation-Error .

Jika Anda mendapatkan label Binary-Validation-Error pada permintaan pull Anda, perbarui perangkat lunak Anda untuk menghapus kode yang terdeteksi sebagai PUA.

Kadang-kadang, alat asli yang digunakan untuk debugging dan aktivitas tingkat rendah dikenali sebagai PUA oleh perangkat lunak antivirus. Ini karena kode debugging yang diperlukan memiliki tanda tangan yang mirip dengan perangkat lunak yang tidak diinginkan. Meskipun praktik pengkodian ini sah, repositori Pengelola Paket Windows sayangnya tidak dapat mengizinkan aplikasi ini.

Pemecahan Masalah Pengajuan

Jika pengiriman Pengelola Paket Windows Anda gagal, Anda dapat menggunakan label yang dijelaskan di atas untuk menyelidiki alasan kegagalan tersebut.

Agar menyelidiki kegagalan pull request, lakukan langkah berikut:

1. Kegagalan permintaan pull muncul di bagian bawah halaman web dengan string Beberapa pemeriksaan tidak berhasil. Pilih tautan Detail di samping validasi yang gagal untuk masuk ke halaman Azure Pipelines.

   

2. Pada halaman Azure Pipelines, pilih tautan 0 kesalahan/0 peringatan .

   

3. Pada halaman berikutnya, pilih tugas yang gagal.

   

4. Halaman berikutnya memperlihatkan output untuk pekerjaan yang gagal. Output akan membantu Anda mengidentifikasi perubahan yang perlu Anda lakukan untuk memperbaiki manifes.

   Dalam contoh berikut, kegagalannya adalah selama tugas Validasi Penginstalan.