تطوير إضافات Discourse - الجزء 4 - إعداد git

[Discourse]

البرنامج التعليمي السابق: Developing Discourse Plugins - Part 3 - Add custom site settings

---

الآن بعد أن أصبح المكون الإضافي (plugin) الخاص بك أكثر تطوراً، فقد حان الوقت لتكون أكثر تطوراً في كيفية تطويره.

نقترح عليك استخدام git للتحكم في الإصدارات للمكون الإضافي الخاص بك. نوصي أيضاً باستخدام github لمشاركة كود المكون الإضافي الخاص بك مع الآخرين.

إنشاء مستودع Git الخاص بك

بمجرد إنشاء حسابك على Github، قم بزيارة هذا الرابط لإنشاء مستودع جديد. يمكنك تسميته ما تشاء، ولكن بشكل عام، من الجيد أن يبدأ الاسم بـ discourse-. تأكد من أن المستودع عام. إليك كيف بدت شاشتي:

إنشاء مجلد العمل المحلي الخاص بك

في هذه المرحلة، أقوم بإنشاء دليل محلي على جهاز الكمبيوتر الخاص بي للاحتفاظ بالمكون الإضافي. عادةً ما أضع المجلد الخاص بي في ~/code ولكن يمكنك وضعه في أي مكان تريده على جهاز الكمبيوتر الخاص بك:

mkdir -p ~/code/discourse-plugin-test
cd ~/code/discourse-plugin-test

الآن دعنا نتبع التعليمات من github لتهيئة المستودع باستخدام ملف README:

echo "# discourse-plugin-test" >> README.md
git init
git add README.md
git commit -m "first commit"
git remote add origin git@github.com:eviltrout/discourse-plugin-test.git
git push -u origin main

أخيراً، قم بإنشاء ملف plugin.rb للمكون الإضافي الخاص بك كما هو موضح في الجزء الأول. لهذا المثال، قمت للتو بإنشاء ملف وهمي:

plugin.rb

# name: discourse-plugin-test
# about: Shows how to set up Git
# version: 0.0.1
# authors: Robin Ward

إنشاء رابط رمزي (symlink)

نظراً لأنك اتبعت دليل المطور developer guide الخاص بنا، يجب أن يكون لديك نسخة من Discourse مستخرجة على جهاز الكمبيوتر الخاص بك في مكان ما. لقد استخرجتها في ~/code/discourse ولكن مرة أخرى، كان بإمكانك وضعها في أي مكان ويجب أن يعمل هذا على أي حال إذا قمت بتعديل الكود التالي وفقًا لذلك:

cd ~/code/discourse/plugins
ln -s ~/code/discourse-plugin-test .

أنشأ الكود أعلاه رابطًا رمزيًا بين كود Discourse الخاص بك ومجلد المكون الإضافي. أعد تشغيل خادم التطوير الخاص بك ويجب أن تجد أن المكون الإضافي الخاص بك يعمل!

جمال هذا الإعداد هو أنه يمكنك فقط إيداع المكون الإضافي الخاص بك في github وعدم القلق بشأن قاعدة كود Discourse التي يعيش بداخلها. سيتم عزل التغييرات الخاصة بك في المكون الإضافي نفسه. إذا كنت بحاجة إلى تعديل كود Discourse، فلا يزال بإمكانك القيام بذلك، ولكن سيتتبع git التغييرات بشكل منفصل!

أوصي باستخدام نافذة محرر واحدة لقاعدة كود المكون الإضافي الخاص بك ونافذة واحدة لـ Discourse نفسه. من الأسهل عندما تفكر فيهما كشيئين مختلفين.

---

المزيد في السلسلة

الجزء 1: أساسيات المكونات الإضافية
الجزء 2: منافذ المكون الإضافي
الجزء 3: إعدادات الموقع
الجزء 4: هذا الموضوع
الجزء 5: واجهات المسؤول
الجزء 6: اختبارات القبول
الجزء 7: انشر المكون الإضافي الخاص بك

---

يتم التحكم في إصدار هذه الوثيقة - اقترح تغييرات على github.

[AhmadF.Cheema]

• After many frustrating attempts, found out that apparently ln -s does not work in a Windows environment, or atleast not how it should.
• ln -s essentially just copy-pasted the plugin folder into the discourse/plugins folder
• Apparently, in Windows the way to create symbolic links is to use the mklink command in command prompt (run as administrator, and this command does not natively run in Windows PowerShell either).
• Using the mklink command (with both arguments /d and /h), although the created symbolic link could be seen present in the directory, the plugin was not working with discourse (and also not showing in /admin/plugins).
• I tried this multiple times with restarting the rails server, deleting the tmp folder, but to no avail.

@eviltrout, any idea what could I be doing wrong?

[eviltrout (Robin Ward)]

I assume you are using Vagrant on windows? If you can’t get the symbolic links sent over, I think the only way you can do it is to copy the plugin into discourse/plugins manually and work from there. It should work as long as you are not making changes to the core discourse app at the same time, which confuses git.

When your plugin is ready, you’ll want to copy it to another directory to package it up for git.

[AhmadF.Cheema]

Yeah, OK this should be fine too.
Although the OCD side of me, much preferred the comparatively “cleaner” symbolic links method.

Anyway, Thanks.

[pacharanero (Marcus Baw)]

@AhmadF.Cheema I had similar problems with the symlinking using Vagrant 1.9.8 on Linux, and a completely standard Discourse Vagrant development environment as per the docs.

The problem is simple when you look into it. From the scope of inside the Vagrant VM, the destination of the symlink is not a valid path. Try executing the command ls -al in the plugins directory inside your VM (in a standard install this is at /vagrant/plugins)

vagrant@discourse:/vagrant/plugins$ ls -al
total 36
drwxr-xr-x 1 vagrant vagrant 4096 Oct 22 09:08 ./
drwxr-xr-x 1 vagrant vagrant 4096 Oct 22 09:10 ../
drwxr-xr-x 1 vagrant vagrant 4096 Sep  7 19:51 discourse-details/
drwxrwxr-x 1 vagrant vagrant 4096 Oct 21 13:56 discourse-narrative-bot/
drwxr-xr-x 1 vagrant vagrant 4096 Oct 21 13:56 discourse-nginx-performance-report/
drwxr-xr-x 1 vagrant vagrant 4096 Sep  7 19:51 discourse-plugin-outlet-locations/
drwxrwxr-x 1 vagrant vagrant 4096 Oct 21 13:56 discourse-presence/
lrwxrwxrwx 1 vagrant vagrant   55 Oct 22 09:08 my-basic-plugin -> /home/marcus/code/discourse/my-basic-plugin
drwxr-xr-x 1 vagrant vagrant 4096 Oct 21 13:56 lazyYT/
drwxr-xr-x 1 vagrant vagrant 4096 Oct 21 13:56 poll/

As you can see, the path /home/marcus/code/discourse/my-basic-plugin cannot possibly be accessible from the VM because it doesn’t exist inside the VM!

The solution is to delete the externally created symlink and set up a separate shared folder in Vagrant, by adding a line to your Vagrantfile:

config.vm.synced_folder "/home/marcus/code/my-basic-plugin",  "/my-basic-plugin"

Then restart the Vagrant VM: vagrant halt && vagrant up so that this change is picked up

Now, when you enter your VM via SSH using vagrant ssh you can create a symlink inside the VM:

cd /vagrant/plugins
ln -s /my-basic-plugin .

Now you can develop in a neatly isolated local folder, and have the neat Git workflow that @eviltrout describes, and the symlinking happens inside the VM. Note that outside the VM, the symlink will be broken - but this shouldn’t matter for our purposes.

[sam (Sam Saffron)]

If you are developing on Linux using our docker based dev is way simpler

[schungx (Stephen Chung)]

Windows symlinks are different from Unix symlinks, thus your confusion. Windows synlinks are very fussy, requiring particular versions of OS to support and sometimes applications must be written to be aware of this. In other words, the stars must line up perfectly for windows symlinks to work.

A hard link (/H) I dont think work with directories. Your /D makes a symlink on a directory, trumping your /H (which is used to create a hard link to a file, not a directory).

Confusing? Welcome to Windows.

There are four types of links in Windows:

• MKLINK (no flags) – symbolic link to file
• MKLINK /H – hard link to file
• MKLINK /D – symbolic link to directory
• MKLINK /J – junction (i.e. hard link) to directory

What you need is is a junction which is Windows-speak for hard link to a directory.

Do MKLINK /J to your plugins directory and the system will treat it as a subdirectory. In fact it won’t know otherwise. Beware, it is not common to have a Windows directory (folder in Windows-speak) to point to the same place as another directory, so you’ll get confused very easy and forget that both are the same things.

That’s why you’ll need to run the command in Administrator mode, otherwise Windows won’t let you create the directory junction.

[pacharanero (Marcus Baw)]

Thanks for the info regarding Windows symlinks @schungx - it should be of help to the OP.

The workaround I described should work fine on any platform, since the symlinks happen inside the (Ubuntu) vagrant box

M

[schungx (Stephen Chung)]

Yup, you’re right. If you can avoid it, avoid messing with Windows. Windows is very picky and may choose to die or go wrong at the most unfortunate moment…

[1c7 (Cheng Zheng)]

Work for me! 2018-4-29

1. I put discourse & my plugin in Desktop

instead of put 1c7-plugin under discourse/plugin

2. and put a “alias” into discourse/plugins folder

alias is a macOS concept,
it’s the same things as ln -s command

3. Discourse correctly load the plugin

(After reboot server with rails s)

4. Now they are separated, use git to manage code is much easier

Thanks!

[maaatt]

تعذر تشغيل الرابط الرمزي في إعداد Docker الخاص بنظام macOS. تعمل المكونات الإضافية فقط إذا تم نسخها مباشرة إلى مجلد المكونات الإضافية.