பங்களிப்பு¶

பங்களிப்புகள் வரவேற்கப்படுகின்றன!

களஞ்சியம் gitlab.com/yaal/canaille இல் புரவலன் செய்யப்பட்டுள்ளது.

விவாதிக்கவும்¶

நீங்கள் ஒரு நற்பொருத்தம் அல்லது பிழைத்திருத்தத்தை செயல்படுத்த விரும்பினால், அதை எங்களுடன் bugtracker அல்லது மேட்ரிக்ச் அறையில் இல் விவாதிப்பதன் மூலம் தொடங்கவும். பிழை உறுதிப்படுத்தப்பட்டாலோ அல்லது நற்பொருத்தங்கள் சாலை வரைபடத்தில் பொருந்தினாலோ, நீங்கள் GitLab இல் ஒன்றிணைக்கும் கோரிக்கையைத் திறக்கலாம். உங்கள் பங்களிப்பு ஏற்றுக்கொள்ளப்படுவதற்கு, சோதனைத் தொகுப்பானது முழு பாதுகாப்புடன் தேர்ச்சி பெற்றிருக்க வேண்டும்.

வளர்ச்சி சூழல்¶

நீங்கள் டெவலப்மெண்ட் சர்வரை உள்ளூரில் அல்லது கப்பல்துறை மூலம் இயக்கலாம்.

டெவலப்மெண்ட் சர்வரைத் தொடங்கிய பிறகு, நீங்கள் பல சேவைகளுக்கான அணுகலைப் பெறுவீர்கள்:

canaille.localhost:5000 இல் ஒரு கேனைல் சர்வர்
client.localhost:4000 இல் ஒரு போலி கிளையன்ட்
maildump.localhost:1080 இல் ஒரு மெயில் கேட்சர்

canaille சேவையகம் சில இயல்புநிலை பயனர்களைக் கொண்டுள்ளது:

ஒரு வழக்கமான பயனர் உள்நுழைவு மற்றும் கடவுச்சொல் பயனர்;
உள்நுழைவு மற்றும் கடவுச்சொல் மதிப்பீட்டாளர் என்ற மதிப்பீட்டாளர் பயனர்;
நிர்வாகி மற்றும் கடவுச்சொல் நிர்வாகம் என்ற நிர்வாகி பயனர்;
உள்நுழைந்த புதிய பயனர் சேம்ச். இந்தப் பயனருக்கு இதுவரை கடவுச்சொல் இல்லை, மேலும் உள்நுழைவதற்கான அவரது முதல் முயற்சியானது கடவுச்சொல் துவக்க மின்னஞ்சலை அனுப்பும் (smtp சேவையகம் கட்டமைக்கப்பட்டிருந்தால்).

பின்தளங்கள்¶

Canaille பல பின்தளங்களுடன் வருகிறது:

ஒரு இலகுரக சோதனை நோக்கம் நினைவக பின்தளம்
ஒரு sql பின்தளம், sqlalchemy அடிப்படையில்
உற்பத்திக்குத் தயாராக இருக்கும் LDAP பின்தளம்

உள்ளக சூழல்¶

உள்ளக வளர்ச்சிக்கு தேவைப்படும் ஒரே கருவி uv. Canaille ஐ ஏக் செய்ய உங்கள் கணினியில் uv நிறுவப்பட்டிருப்பதை உறுதிப்படுத்தவும்.

உங்கள் மேம்பாட்டு சூழலை இதனுடன் தொடங்கவும்:

uv sync --all-groups --all-extras உங்கள் விரல் நுனியில் அனைத்தையும் வைத்திருக்க விரும்பினால். இது உங்கள் கணினியில் நிறுவப்படும் என்று எதிர்பார்க்கும் சில பைதான் சார்புகளை தொகுக்கலாம்.
uv sync --extra front --extra oidc குறைந்தபட்ச வேலை வளர்ச்சி சூழலைக் கொண்டிருக்க வேண்டும். uv pytest --backend memory மூலம் சோதனைகளை இயக்க இது உங்களை அனுமதிக்கும்.
uv sync --extra front --extra oidc --extra sqlite SQLite பின்தள ஆதரவுடன் குறைந்தபட்ச வேலை வளர்ச்சி சூழலைப் பெறவும். இது uv pytest --backend sql மூலம் சோதனைகளை இயக்க உங்களை அனுமதிக்கும்.
uv sync --extra front --extra oidc --extra ldap LDAP பின்தள ஆதரவுடன் குறைந்தபட்ச வேலை வளர்ச்சி சூழலைக் கொண்டிருக்க வேண்டும். இது uv pytest --backend ldap மூலம் சோதனைகளை இயக்க உங்களை அனுமதிக்கும். கானாய்லின் சில சார்புகள் தொகுக்கப்பட வேண்டியிருக்கும், எனவே உங்கள் கணினியில் சிசிசி மற்றும் கார்கோ கிடைக்கிறதா என்பதைச் சரிபார்க்க வேண்டும்.

SQL¶

SQL பின்தளத்தில், டெவலப்மெண்ட் சர்வர் உள்ளக sqlite தரவுத்தளத்தில் தரவை ஏற்றி சேமிக்கும்.

வளர்ச்சி சேவையகத்தை கவிமொ பின்தளத்தில் இயக்கவும்¶

$ uv run devserver

நினைவகம்¶

நினைவக பின்தளத்தில், Canaille நிறுத்தப்படும்போது எல்லா தரவும் இழக்கப்படும்.

வளர்ச்சி சேவையகத்தை நினைவக பின்தளத்தில் இயக்கவும்¶

$ uv run devserver --backend memory

LDAP¶

LDAP பின்தளத்தில், Canaille நிறுத்தப்படும்போது எல்லா தரவும் இழக்கப்படும்.

வளர்ச்சி சேவையகத்தை LDAP பின்தளத்தில் இயக்கவும்¶

$ uv run devserver --backend ldap

Note

நீங்கள் LDAP பின்தளத்தில் டெவலப்மெண்ட் சர்வரை உள்நாட்டில் இயக்க விரும்பினால், உங்கள் கணினியில் OpenLDAP நிறுவப்பட்டிருக்க வேண்டும். இது பொதுவாக slapd அல்லது openldap தொகுப்பு பெயரில் அனுப்பப்படுகிறது.

Warning

Debian அல்லது Ubuntu கணினிகளில், OpenLDAP slapd பைனரி பயன்பாடு apparmor மூலம் கட்டுப்படுத்தப்படலாம், இதனால் சோதனைகள் மற்றும் டெவலப்மெண்ட் சர்வர் தோல்வியடையும். ச்லாப்ட் மீதான ஆடைக் கட்டுப்பாடுகளை அகற்றுவதன் மூலம் இதைத் தணிக்க முடியும்.

$ sudo apt install --yes apparmor-utils
$ sudo aa-complain /usr/sbin/slapd

கப்பல்துறை சூழல்¶

SQL¶

வளர்ச்சி சேவையகத்தை கவிமொ பின்தளத்தில் இயக்கவும்¶

$ cd dev
$ docker compose up

நினைவகம்¶

நினைவக பின்தளத்தில், Canaille நிறுத்தப்படும்போது எல்லா தரவும் இழக்கப்படும்.

வளர்ச்சி சேவையகத்தை நினைவக பின்தளத்தில் இயக்கவும்¶

$ cd dev
$ docker compose --file docker-compose-memory.yml up

LDAP¶

LDAP பின்தளத்தில், Canaille நிறுத்தப்படும்போது எல்லா தரவும் இழக்கப்படும்.

வளர்ச்சி சேவையகத்தை LDAP பின்தளத்தில் இயக்கவும்¶

$ cd dev
$ docker compose --file docker-compose-ldap.yml up

தரவுத்தளத்தை நிரப்பவும்¶

டெவலப்மெண்ட் சர்வர் தரவுத்தளமானது சில சீரற்ற பயனர்கள் மற்றும் குழுக்களுடன் வருகிறது. உங்களுக்கு மேலும் தேவைப்பட்டால், ppulate கட்டளை மூலம் பயனர்களையும் குழுக்களையும் உருவாக்கலாம்:

# If using docker:
$ docker compose exec canaille env CANAILLE__DATABASE=<backend> CANAILLE_CONFIG=conf/canaille.toml uv run canaille populate --nb 100 users  # or docker-compose

# If running in local environment
$ env CANAILLE__DATABASE=<backend> CANAILLE_CONFIG=conf/canaille.toml uv run canaille populate  --nb 100 users

ldap அல்லது sql உள்ளமைவுக் கோப்பைப் பயன்படுத்துவதற்கு மாற்றியமைக்கவும். நினைவக பின்தளத்தில் இது வேலை செய்யாது என்பதை நினைவில் கொள்ளவும்.

அலகு சோதனைகள்¶

சோதனைகளை இயக்க, ஆதரிக்கப்படும் அனைத்து பைதான் சூழல்களையும் சோதிக்க uv ஓடு pytest மற்றும்/அல்லது uv ஓடு tox ஐ இயக்கலாம். இணைப்புகள் ஒன்றிணைவதற்கு முன் அனைத்தும் பச்சை நிறமாக இருக்க வேண்டும்.

குறிப்பிட்ட பின்தளத்தை சோதிக்க நீங்கள் --பேக்கெண்ட் மெமரி, --பேக்கெண்ட் sql அல்லது --பேக்கெண்ட் ldap ஐ பைடெச்ட் மற்றும் டாக்சுக்கு அனுப்பலாம். கவிமொ பின்தளம் மாறுபாடுகளை ஆதரிக்கிறது: --பேக்கெண்ட் sql:postgresql அல்லது --backend sql:sqlite. --பின்னணி sql இரண்டையும் சோதிக்கிறது.

சோதனைக் கவரேச் 100%, முழுமையாக மூடப்படாவிட்டால் இணைப்புகள் ஏற்றுக்கொள்ளப்படாது. uv ஓடு pytest --cov --cov-report=html அல்லது uv ஓடு tox -e coverage -- --cov-report=html மூலம் சோதனைக் கவரேசைச் சரிபார்க்கலாம். புதிதாக உருவாக்கப்பட்ட htmlcov கோப்பகத்தில் உஉகுமொ கவரேச் அறிக்கையைப் பார்க்கலாம்.

ஒருங்கிணைப்பு சோதனைகள்¶

ஒரு வீல் பேக்கேச், பைஇன்ச்டாலர் பைனரி அல்லது கப்பல்துறை படமாக கட்டமைக்கப்பட்டு பயன்படுத்தப்படும்போது, கேனைல் சரியாக வேலை செய்கிறது என்பதை ஒருங்கிணைப்பு சோதனைகள் சரிபார்க்கின்றன. அனைத்து உருவாக்க முறைகளையும் இயக்க:

$ uv run pytest integration/

குறிப்பிட்ட உருவாக்கப் பயன்முறையைச் சோதிக்க, --build=dev (source), --build=package (wheel), --build=pyinstaller (பைனரி), அல்லது --build=docker (கொள்கலன்) ஆகியவற்றைப் பயன்படுத்தவும். முன் கட்டப்பட்ட கலைப்பொருளையும் நீங்கள் சோதிக்கலாம்: --build=pyinstaller:/path/to/binary அல்லது --build=docker:image:tag.

குறியீடு நடை¶

எங்கள் குறியீட்டை வடிவமைக்க பிற கருவிகளுடன் ruff ஐப் பயன்படுத்துகிறோம். அவற்றைச் சமர்ப்பிக்கும் முன் உங்கள் பேட்ச்களில் uv ஓடு tox -e style ஐ இயக்கவும். ஒவ்வொரு கமிட்டியிலும் பாணி சரிபார்ப்பு மற்றும் திருத்தம் செய்ய, uv ஓடு prek install உடன் எங்கள் prek உள்ளமைவைப் பயன்படுத்தலாம்.

Coding agents¶

The use of coding agents in contributions is allowed as long as all the other points of this document are respected, and it does not impact the software quality. Contribution authors MUST understand and be able to explain ANY line of code that has been produced, like the code they write themselves. The use of an agent must be indicated in the PR.

முன்¶

இடைமுகம் Fomantic இடைமுகம் சிஎச்எச் கட்டமைப்பின் மீது கட்டமைக்கப்பட்டுள்ளது. இடைமுகத்தின் மாறும் பகுதிகள் htmx ஐப் பயன்படுத்துகின்றன.

இடைமுகத்தில் சாவாச்கிரிப்டைப் பயன்படுத்துவது சகித்துக்கொள்ளப்படுகிறது, ஆனால் முழு வலைத்தளமும் சாவாச்கிரிப்ட் உதவி இல்லாமல் மற்றும் எந்த அம்ச இழப்பும் இல்லாமல் உலாவிகளுக்கு அணுகக்கூடியதாக இருக்க வேண்டும்.
Fomantic இடைமுகம் காரணமாக, jQuery-ஐச் சார்ந்து இருக்கிறோம், இருப்பினும் புதிய பங்களிப்புகள் jQueryயைச் சார்ந்திருக்கக் கூடாது. தொடர்புடைய சிக்கலைப் பார்க்கவும்.

ஆவணப்படுத்துதல்¶

சோதனைகள் இயங்கும்போது ஆவணங்கள் உருவாக்கப்படுகின்றன:

$ tox -e doc

நீங்கள் கையால் ச்பிங்க்சை இயக்கலாம், இது நச்சு சூழல் துவக்கத்தைத் தவிர்க்கும் என்பதால் வேகமாக இருக்க வேண்டும்:

$ sphinx-build doc build/sphinx/html/en

உருவாக்கப்பட்ட ஆவணங்கள் build/sphinx/html/en இல் அமைந்துள்ளது.

Note

ஆவணப்படுத்தல் `ச்பிங்க்ச்கான்ட்ரிப்-ச்கிரீன்சாட்`_ஐப் பயன்படுத்தி கேனாய்லின் மாறும் திரை சாட்களை உருவாக்குகிறது, அது உள்நாட்டில் `பிளேரைட்`_ஐப் பயன்படுத்துகிறது. நாடக ஆசிரியரை பின்வரும் கட்டளையுடன் துவக்க வேண்டும்:

$ uv run playwright install firefox

குறியீடு மொழிபெயர்ப்பு¶

Weblate மூலம் மொழிபெயர்ப்புகள் செய்யப்படுகின்றன.

பின்வரும் கட்டளைகள் ஆவணங்களாக உள்ளன, பங்களிப்பாளர்களுக்கு செய்தி பிரித்தெடுத்தல் மட்டுமே தேவை. மற்ற அனைத்து படிகளும் தானாகவே வலைபெயர்ப்பு மூலம் செய்யப்படுகின்றன.

செய்தி பிரித்தெடுத்தல்¶

மொழிபெயர்க்கக்கூடிய சரங்களைத் திருத்திய பிறகு, நீங்கள் செய்திகளைப் பிரித்தெடுக்க வேண்டும்:

$ pybabel extract --mapping-file pyproject.toml --copyright-holder="Yaal Coop" --output-file canaille/translations/messages.pot canaille

மொழி சேர்த்தல்¶

பின்வரும் கட்டளையுடன் நீங்கள் கைமுறையாக ஒரு புதிய மொழியைச் சேர்க்கலாம், இருப்பினும் வலைபெயர்ப்பு இதைப் பயன்படுத்துவதால் இது தேவையில்லை:

$ pybabel init --input-file canaille/translations/messages.pot --output-dir canaille/translations --locale <LANG>

பட்டியல் புதுப்பிப்பு¶

பின்வரும் கட்டளையுடன் நீங்கள் பட்டியல்களைப் புதுப்பிக்கலாம், இருப்பினும், புதிய சரங்களைக் கண்டறியும் போது அல்லது ஏற்கனவே உள்ள சில சரங்களை யாராவது மொழிபெயர்க்கும் போது, Weblate தானாகவே மொழி பட்டியல்களை மேம்படுத்துவதால் இது தேவையில்லை. ஒவ்வொரு 24 மணிநேரமும் வலைபெயர்ப்பு புச்கள் நடக்கும்.

$ pybabel update --input-file canaille/translations/messages.pot --output-dir canaille/translations --ignore-obsolete --no-fuzzy-matching --update-header-comment

பட்டியல் தொகுப்பு¶

பின்வரும் கட்டளையுடன் நீங்கள் பட்டியல்களை தொகுக்கலாம், இருப்பினும் இது தேவைப்படாது, ஏனெனில் அலகு சோதனைகளை இயக்குவதற்கு முன்பும், டெமோவைத் தொடங்குவதற்கு முன்பும் மற்றும் Canaille பைதான் தொகுப்பைத் தொகுக்கும் முன்பும் பட்டியல்கள் தானாகவே தொகுக்கப்படும்:

$ pybabel compile --directory canaille/translations --statistics

ஆவண மொழிபெயர்ப்பு¶

Weblate மூலம் மொழிபெயர்ப்புகள் செய்யப்படுகின்றன.

பின்வரும் கட்டளைகள் ஆவணங்களாக உள்ளன, செய்தி பிரித்தெடுத்தல் மற்றும் மொழி சேர்த்தல் மட்டுமே பங்களிப்பாளர்களுக்கு தேவை.

செய்தி பிரித்தெடுத்தல்¶

$ sphinx-build --builder gettext doc doc/locales

மொழி சேர்த்தல்¶

$ sphinx-intl update --pot-dir doc/locales --locale-dir doc/locales -l fr

ஆவணங்களை வேறொரு மொழியில் உருவாக்கவும்¶

$ sphinx-build --builder html --define language=fr doc build/sphinx/html/fr

தொகுப்புகளை உருவாக்குங்கள்¶

ஒவ்வொரு உறுதிப்பாட்டிலும் உருவாக்க செயல்முறைகள் செயல்படுகின்றனவா என்பதை தொஒ சரிபார்க்கிறது.

பைதான் தொகுப்பு¶

பைதான் பேக்கேசிங் படி uv ஆல் கவனிக்கப்படுகிறது:

$ uv build

பைனரி கோப்பு¶

கேனாய்லின் ஒற்றை பைனரியை உருவாக்க, வெளியீடு சார்புக் குழுவை நிறுவுவதன் மூலம் பைன்ச்டாலரைப் பயன்படுத்தலாம்:

$ uv sync --group release --all-extras --no-dev
$ uv run pyinstaller canaille.spec

கப்பல்துறை¶

$ docker build -t canaille .

தொகுப்புகளை வெளியிடவும்¶

பைதான் தொகுப்பு¶

$ uv publish --publish-url https://test.pypi.org/legacy/
$ uv publish

கப்பல்துறை¶

DockerHub இல் நீங்கள் ஒருமுறை அங்கீகரிக்க வேண்டும்.

$ docker login --username <hub docker login>

பின்னர் நீங்கள் படங்களை அழுத்தலாம்.

$ export CANAILLE_VERSION=$(uv run python -c "from importlib.metadata import version; print(version('canaille'))")
$ docker tag canaille:latest "yaalcoop/canaille:latest"
$ docker tag canaille:latest "yaalcoop/canaille:${CANAILLE_VERSION}"
$ docker push yaalcoop/canaille:latest
$ docker push yaalcoop/canaille:${CANAILLE_VERSION}

புதிய வெளியீட்டை வெளியிடவும்¶

ஒரு அறிவிலி டேக் தள்ளப்படும் போது, தொகுப்பு கட்டும் செயல்முறை தொஒ ஆல் கவனிக்கப்படுகிறது. இது வெவ்வேறு கடைகளில் வெவ்வேறு தொகுப்புகளை வெளியிடுகிறது.

uv sync --all-extras --all-groups --upgrade உடன் சார்புகள் புதுப்பித்த நிலையில் உள்ளதா எனச் சரிபார்த்து, பிரிக்கப்பட்ட கமிட்களில் அதற்கேற்ப சார்புகளைப் புதுப்பிக்கவும்;
ஆதரிக்கப்படும் ஒவ்வொரு பைதான் பதிப்பிற்கும் சோதனைகள் பச்சை நிறத்தில் உள்ளனவா என்பதையும், uv ஓடு tox ஐ இயக்குவதன் மூலம், கவரேச் இன்னும் 100% இல் உள்ளதா எனச் சரிபார்க்கவும். தொஒ பச்சை நிறத்தில் இருப்பதை அழுத்தி சரிபார்க்கவும்;
வெளியீட்டு குறிப்புகள் பகுதி சரியாக நிரப்பப்பட்டுள்ளதா என சரிபார்க்கவும்;
pyproject.toml இல் பதிப்பு எண்ணை அதிகரிக்கவும்;
சிட் கமிட் உடன் உறுதி;
git tag --annotate XX.YY.ZZ --message "Release version XX.YY.ZZ" உடன் உறுதியைக் குறியிடவும்;
git push --tags மூலம் வெளியீட்டு உறுதி மற்றும் புதிய குறிச்சொல்லை களஞ்சியத்தில் அழுத்தவும்.