Ana içeriğe geç

Katkıda Bulunmak

Flarum gelişimine katkıda bulunmak ister misiniz? Bu harika! Bir hata raporu açmaktan bir çekme isteği (PR) oluşturmaya kadar: her katkı takdir edilir ve memnuniyetle karşılanır. Flarum wouldn't be possible without our community contributions.

Katkıda bulunmadan önce lütfen davranış kurallarını okuyun.

Bu belge, Flarum'a kod katkısında bulunmak isteyen geliştiriciler için bir kılavuzdur. Yeni başlıyorsanız, Flarum'un nasıl çalıştığı hakkında biraz daha fazla bilgi edinmek için Uzantı belgelerindeki Başlarken belgelerini okumanızı öneririz.

Ne Üzerinde Çalışmalı​

⚡ Have Real Impact. There are thousands of Flarum instances, with millions of aggregate end users. By contributing to Flarum, your code will have a positive impact on all of them.

🔮 Shape the Future of Flarum. We have a long backlog, and limited time. If you're willing to champion a feature or change, it's much more likely to happen, and you'll be able to enact your vision for it. Plus, our roadmap and milestones are set by our core development team, and all of us started as contributors. The best road to influence is contributing.

🧑‍💻 Become a Better Engineer. Our codebase is modern, and we heavily value good engineering and clean code. There's also a lot of interesting, challenging problems to solve regarding design, infrastructure, performance, and extensibility. Especially if you're a student or early in your career, working on Flarum is a great opportunity to build development skills.

🎠 It's Fun! We really enjoy working on Flarum: there's a lot of interesting challenges and fun features to build. We also have an active community on our forums and Discord server.

Geliştirme Kurulumu​

Nelerin yapılması gerektiğine dair genel bir bakış için Milestones dönüm noktalarına göz atın. Başlaması nispeten kolay olması gereken sorunların bir listesi için Good first issue etiketine bakın. If there's anything you're unsure of, don't hesitate to ask! All of us were just starting out once.

Devam etmeyi ve bir şey üzerinde çalışmayı planlıyorsanız, lütfen ilgili konu hakkında yorum yapın veya önce yeni bir sorun oluşturun. Bu şekilde değerli çalışmalarınızın boşuna olmamasını sağlayabiliriz.

Since Flarum is so extension-driven, we highly recommend our extension docs as a reference when working on core, as well as for bundled extensions. You should start with the introduction for a better understanding of our extension philosophy.

Geliştirme İş Akışı​

Setting Up a Local Codebase​

flarum/flarum is a "skeleton" application which uses Composer to download the core package and a bunch of extensions. Source code for Flarum core, extensions, and all packages used by the aforementioned is located in the Flarum monorepo flarum/framework. In order to contribute to these, you'll need to fork and clone the monorepo repository locally, and then add it to your dev environment as a Composer path repository:

git clone https://github.com/flarum/flarum.git
cd flarum

# Or, when you want to clone directly into the current directory
git clone https://github.com/flarum/flarum.git .
# Note, the directory must be empty

# Set up a Composer path repository for Flarum monorepo packages
composer config repositories.0 path "PATH_TO_MONOREPO/*/*"
git clone https://github.com/<username>/framework.git PATH_TO_MONOREPO

Tipik bir katkı iş akışı şuna benzer:

Son olarak, kurulumu dizin havuzlarından tamamlamak için composer install çalıştırın.

Yerel kurulumunuz kurulduktan sonra, config.php içinde debug modunu etkinleştirdiğinizden ve php yapılandırmanızda display_errors u On olarak ayarladığınızdan emin olun. Bu, hem Flarum hem de PHP için hata ayrıntılarını görmenize olanak sağlar. Debug mode also forces a re-compilation of Flarum's asset files on each request, removing the need to call php flarum cache:clear after each change to the extension's JavaScript or CSS.

Flarum'un ön uç kodu ES6'da yazılır ve JavaScript'e aktarılır. During development you will need to recompile the JavaScript using Node.js and yarn. Please do not commit the resulting dist files when sending PRs; this is automatically taken care of when changes are merged into the main branch.

To contribute to the frontend, first install the JavaScript dependencies. The monorepo uses yarn workspaces to easily install JS dependencies across all packages within.

cd packages/framework
yarn install

Then you can watch JavaScript files for changes during development:

cd framework/core/js
yarn dev

The process is the same for extensions.

cd extensions/tags/js
yarn dev

Development Tools​

After you've forked and cloned the repositories you'll be working on, you'll need to set up local hosting so you can test out your changes. Flarum doesn't currently come with a development server, so you'll need to set up Apache/NGINX/Caddy/etc to serve this local Flarum installation.

Alternatively, you can use tools like, Laravel Valet (Mac), XAMPP (Windows), or Docker-Flarum (Linux) to serve a local forum.

Most Flarum contributors develop with PHPStorm or Visual Studio Code.

Kodlama Stili​

A typical contribution workflow looks like this:

  1. 🌳 Uygun dalı yeni bir özellik dalına ayırın.

    • Hata düzeltmeleri en son kararlı dala gönderilmelidir.
    • Mevcut Flarum sürümüyle geriye dönük olarak tamamen uyumlu olan Küçük özellikler, en son kararlı dala gönderilebilir.

  2. 🔨 Bir kod yazın.

    • Kodlama Stili hakkında aşağıya bakın.
    • Ana özellikler her zaman gelecek Flarum sürümünü içeren "ana" şubeye gönderilmelidir.
    • Major features should always be sent to the main branch, which contains the upcoming Flarum release.
    • Dahili olarak <initials>/<short-description> (eg. tz/refactor-frontend) adlandırma şemasını kullanıyoruz.

  3. 🚦 Kodunuzu test edin.

    • Hataları giderirken veya özellikler eklerken gerektiği gibi birim testleri ekleyin.

  4. 💾 Kodunuzu açıklayıcı bir mesajla işleyin.

    • Add unit tests as necessary when fixing bugs or adding features.
    • Test paketini ilgili paket klasöründeki vendor/bin/phpunit ile çalıştırın.
    • See here for more information about testing in Flarum.

  5. 🎁 GitHub'da bir Çekme İsteği (PR) gönderin.

    • Değişikliğiniz mevcut bir sorunu çözüyorsa (genellikle bu, 123 numaralı sorun numarası olmak üzere yeni satırda "123 numaralı düzeltmeleri" içermelidir).
    • Follow the Conventional Commits specification.
    • Fix commits should describe the issue fixed, not how it was fixed.

  6. 🤝 Onay için Flarum ekibiyle iletişim kurun.

    • Çekme talebi şablonunu doldurun.
    • Değişikliğiniz görselse, değişikliği gösteren bir ekran görüntüsü veya GIF ekleyin.
    • JavaScript dist dosyalarını DERLEMEYİN. Bunlar birleştirme sırasında otomatik olarak derlenecektir.

  7. 🕺 Dans et tıpkı Flarum'a katkıda bulunduğun gibi.

    • Ekip üyeleri kodunuzu inceleyecek. Bazı değişiklikler veya iyileştirmeler veya alternatifler önerebiliriz, ancak küçük değişiklikler için çekme talebinizin hızla kabul edilmesi gerekir.
    • Geri bildirimi ele alırken, üzerine yazmak veya ezmek yerine ek taahhütleri itin (birleştireceğiz).

  8. 🕺 Dance like you just contributed to Flarum.

Geliştirme araçları​

In order to keep the Flarum codebase clean and consistent, we have a number of coding style guidelines that we follow. When in doubt, read the source code.

Don't worry if your code styling isn't perfect! StyleCI and Prettier will automatically check formatting for every pull request. This allows us to focus on the content of the contribution, not the code style.

PHP​

Flarum follows the PSR-2 coding standard and the PSR-4 autoloading standard. On top of this, we conform to a number of other style rules. We use PHP 7 type hinting and return type declarations where possible, and PHPDoc to provide inline documentation. Try and mimic the style used by the rest of the codebase in your contributions.

  • Flarum\Discussion, not Flarum\Discussions)
  • Arayüzlerin sonuna Interface eklenmelidir (ör. MailableInterface)
  • Abstract sınıflarının önüne Abstract yazılmalıdır (ör AbstractModel)
  • Özelliklerin sonuna Trait eklenmelidir (ör. ScopeVisibilityTrait)

JavaScript​

Flarum's JavaScript mostly follows the Airbnb Style Guide. We use ESDoc to provide inline documentation.

Çeviriler​

Columns should be named according to their data type:

  • DATETIME veya TIMESTAMP: {verbed}_at (ör. created_at, read_at) veya {verbed}_until (ör. suspended_until)
  • INT bu bir sayıdır: {noun}_count (ör. comment_count, word_count)
  • Yabancı anahtar: {verbed}_{entity}_id (ör. hidden_user_id)
    • Fiil birincil ilişki için ihmal edilebilir (ör. Yazının yazarı sadece user_id)
  • BOOL: is_{adjective} (ör. is_locked)

Tables should be named as follows:

  • Çoğul biçim kullanın (discussions)
  • Birden çok kelimeyi alt çizgilerle ayırın (access_tokens)
  • İlişki tabloları için, iki tablo adını alfabetik sırayla bir alt çizgi ile tekil biçimde birleştirin (ör. discussion_user)

CSS​

Flarum's CSS classes roughly follow the SUIT CSS naming conventions using the format .ComponentName-descendentName--modifierName.

Translations​

We use a standard key format to name translation keys descriptively and consistently.

Katılımcı Lisans Sözleşmesi​

By contributing your code to Flarum you grant the Flarum Foundation (Stichting Flarum) a non-exclusive, irrevocable, worldwide, royalty-free, sublicensable, transferable license under all of Your relevant intellectual property rights (including copyright, patent, and any other rights), to use, copy, prepare derivative works of, distribute and publicly perform and display the Contributions on any licensing terms, including without limitation: (a) open source licenses like the MIT license; and (b) binary, proprietary, or commercial licenses. Except for the licenses granted herein, You reserve all right, title, and interest in and to the Contribution.

You confirm that you are able to grant us these rights. You represent that You are legally entitled to grant the above license. If Your employer has rights to intellectual property that You create, You represent that You have received permission to make the Contributions on behalf of that employer, or that Your employer has waived such rights for the Contributions.

You represent that the Contributions are Your original works of authorship, and to Your knowledge, no other person claims, or has the right to claim, any right in any invention or patent related to the Contributions. You also represent that You are not legally obligated, whether by entering into an agreement or otherwise, in any way that conflicts with the terms of this license.

The Flarum Foundation acknowledges that, except as explicitly described in this Agreement, any Contribution which you provide is on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.