Recent

Author Topic: Editing wiki.  (Read 707 times)

Rintaro

  • Newbie
  • Posts: 3
Editing wiki.
« on: September 01, 2024, 04:42:46 am »
Hi,

I've been a big fan of Object Pascal since Delphi 1, and I would love to contribute to the Lazarus community. I wonder if there is any guideline for editing the wiki. If there is, I'd appreciate being directed to it.

My main concern is whether I should revise the entire sample code or add new code alongside the original. I'm also interested in any suggested best practices for revising sample code.

To be specific, I'm working with Raspberry Pi. I found a sample code on the wiki for accessing GPIO-thanks! However, it didn't cover the Raspberry Pi 4. I did some research and added "minimum" information so that it now covers the Raspberry Pi 4.

After that, I continued working and made further improvements to the sample. I feel that the original sample doesn't follow Pascal conventions well, so the changes I made are quite substantial. I assume I should simply overwrite the existing sample, but I want to respect the original contributor. Therefore, I wonder if there are any guidelines for making contributions peacefully.


Aruna

  • Sr. Member
  • ****
  • Posts: 457
Re: Editing wiki.
« Reply #1 on: September 01, 2024, 05:02:07 am »
Hi,

I've been a big fan of Object Pascal since Delphi 1, and I would love to contribute to the Lazarus community. I wonder if there is any guideline for editing the wiki. If there is, I'd appreciate being directed to it.

My main concern is whether I should revise the entire sample code or add new code alongside the original. I'm also interested in any suggested best practices for revising sample code.

To be specific, I'm working with Raspberry Pi. I found a sample code on the wiki for accessing GPIO-thanks! However, it didn't cover the Raspberry Pi 4. I did some research and added "minimum" information so that it now covers the Raspberry Pi 4.

After that, I continued working and made further improvements to the sample. I feel that the original sample doesn't follow Pascal conventions well, so the changes I made are quite substantial. I assume I should simply overwrite the existing sample, but I want to respect the original contributor. Therefore, I wonder if there are any guidelines for making contributions peacefully.
Regarding your specific concerns:

Revising vs. Adding New Code: If the original sample code is outdated or doesn’t follow current Pascal conventions, it’s generally a good idea to make revisions to improve it. However, if the changes are substantial, it might be useful to add your improved version alongside the original sample. This way, users can benefit from both the original and updated versions. You might also want to include a note explaining the changes you made and the reasons behind them. You can create a hyperlink and create a separate content page that you are free to do as you please. This way the original contributors work remains and teh link points to your improvements. Never overwrite anything without asking and getting a consensus from the community first.

Best Practices: When revising sample code, consider the following best practices:
Respect the Original Work: Acknowledge the original contributor’s work and provide clear documentation on what has been changed or improved.
Document Changes: Explain your changes and improvements in the edit summary or in a dedicated section of the wiki. This helps others understand the context and rationale behind the updates.
Follow Conventions: Ensure your code follows Object Pascal conventions and best practices. This makes the code more accessible and maintainable for other users.

Contributing Peacefully: To ensure a smooth contribution process:
Communicate: If possible, reach out to the original contributor to discuss your proposed changes. This fosters collaboration and respect for their work.
Be Transparent: Provide clear explanations for why changes are necessary and how they improve the sample code.

It’s great that you’ve already made significant improvements, including updating the sample code for Raspberry Pi 4. Your contributions will undoubtedly be valuable to the community.

These may come in handy:
https://wiki.freepascal.org/Help:Editing
https://wiki.freepascal.org/wiki_documentation
https://wiki.freepascal.org/Main_Page

« Last Edit: September 01, 2024, 05:12:13 am by Aruna »
Debian GNU/Linux 11 (bullseye)
https://pascal.chat/

JuhaManninen

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 4519
  • I like bugs.
Re: Editing wiki.
« Reply #2 on: September 01, 2024, 08:33:57 am »
Aruna's advice is good when the existing information is well structured.
However the nature of Wiki can lead to poorly structured messy pages with partly duplicate information scattered around. This happens because everybody adds text but nobody dares to remove or restructure it.
This problem is inherent to any community Wiki. There is no editor-in-chief taking care of it.
I have noticed myself that removing old text is more difficult than adding new one, even when it would improve things and make information easier and faster to find..

Thus I suggest a more aggressive stance for Wiki editing than Aruna has.
Lots of information is outdated and the authors have moved on years ago.
If you have a clear vision about how to improve both the information and the structure of pages, please do so.
Yes, it is a good idea to mention it here in forum. Then others can review it and comment.
The Wiki remembers its history. Old data can be restored if things go wrong.
Mostly Lazarus trunk and FPC 3.2 on Manjaro Linux 64-bit.

Rintaro

  • Newbie
  • Posts: 3
Re: Editing wiki.
« Reply #3 on: September 01, 2024, 09:15:04 am »
Thank you, Aruna. Before overwriting, I plan to discuss this in the forum. Which category would you recommend for this topic—Lazarus/ Programming/ General? I couldn't find a category that seems appropriate.

Rintaro

  • Newbie
  • Posts: 3
Re: Editing wiki.
« Reply #4 on: September 01, 2024, 09:27:08 am »
Aruna's advice is good when the existing information is well structured.
However the nature of Wiki can lead to poorly structured messy pages with partly duplicate information scattered around. This happens because everybody adds text but nobody dares to remove or restructure it.
This problem is inherent to any community Wiki. There is no editor-in-chief taking care of it.
I have noticed myself that removing old text is more difficult than adding new one, even when it would improve things and make information easier and faster to find..

Thus I suggest a more aggressive stance for Wiki editing than Aruna has.
Lots of information is outdated and the authors have moved on years ago.
If you have a clear vision about how to improve both the information and the structure of pages, please do so.
Yes, it is a good idea to mention it here in forum. Then others can review it and comment.
The Wiki remembers its history. Old data can be restored if things go wrong.
Thank you, JuhaManninen. I feel the same way, which is why I asked here first. I'd like to discuss this in the forum.  People's opinions will likely depend on how my source code looks. I'll see what I can do. It might be a good idea to post the code on GitHub first.

dbannon

  • Hero Member
  • *****
  • Posts: 3074
    • tomboy-ng, a rewrite of the classic Tomboy
Re: Editing wiki.
« Reply #5 on: September 01, 2024, 10:17:17 am »
Yes, I very much agree with what Juha says, the problem with Wiki (not just FPC/Lazarus Wiki) is its far, far easier to add content than to correct out of date or just plain wrong content.  And all that existing content, possibly wrong content make it much harder to find what you are looking for.

That being said Rintaro, I was puzzeled to see your comment that current info does not work with RasPi 4.  So, I looked up your changes. (HINT - when commenting on Wiki content, great idea to include a link to the content under question). And I found this -
Quote
The easiest one is to launch Lazarus as root.

on this page : https://wiki.freepascal.org/index.php?title=Lazarus_on_Raspberry_Pi

As a very long term Unix/Linux sysadmin, there is almost no circumstance where its a good idea to run something like Lazarus as root.  If your resulting application MUST be run as root, its quite easy to use a script or other tricks to give it (and only it) root access but please don't run gui apps that make extensive changes to its own files as root. Ever.  Worthwhile looking at what can be done with the sudo command for example.

So, I will rephrase my advice about editing wiki pages, "yes, please make changes, not just additions, but do please make sure you know what you are doing first".

Could you also, please, explain what is different about the Raspi 4 that requires this special treatment ?  Are you absolutely sure the issue you are looking at relates to the hardware or, maybe, the operating system ?  Does it apply to the RasPi 5 too ? Since when ?  I run some superficial code on a RasPi and jump from a RasPi4 (where the dev work is done) to a RasPi 3 (where the real app runs) without any apparent changes. Maybe its a performance issue ?

Rintaro, please don't be discouraged, I value your input here, its a genuine seeking of information, not just getting in your way !

Davo
Lazarus 3, Linux (and reluctantly Win10/11, OSX Monterey)
My Project - https://github.com/tomboy-notes/tomboy-ng and my github - https://github.com/davidbannon

MarkMLl

  • Hero Member
  • *****
  • Posts: 7649
Re: Editing wiki.
« Reply #6 on: September 01, 2024, 11:11:36 am »
Yes, I very much agree with what Juha says, the problem with Wiki (not just FPC/Lazarus Wiki) is its far, far easier to add content than to correct out of date or just plain wrong content.  And all that existing content, possibly wrong content make it much harder to find what you are looking for.

I agree, and there's also working or "aspirational" notes in there, i.e. "this is what we were thinking about in 2010".

Quote
As a very long term Unix/Linux sysadmin, there is almost no circumstance where its a good idea to run something like Lazarus as root.  If your resulting application MUST be run as root, its quite easy to use a script or other tricks to give it (and only it) root access but please don't run gui apps that make extensive changes to its own files as root. Ever.  Worthwhile looking at what can be done with the sudo command for example.

I agree and would also add that some widgetsets will refuse to start a GUI-oriented program if they don't like the combination of UID and EUID (e.g. something's been setuid root).

The only reason (IME) that you might need to run Lazarus as root is if you're attempting to e.g. change POSIX capabilities after something's been compiled. I submitted a patch to add a "run this command as this user" facility years ago, but it was ignored apparently since it wasn't portable to Windows.

MarkMLl
MT+86 & Turbo Pascal v1 on CCP/M-86, multitasking with LAN & graphics in 128Kb.
Logitech, TopSpeed & FTL Modula-2 on bare metal (Z80, '286 protected mode).
Pet hate: people who boast about the size and sophistication of their computer.
GitHub repositories: https://github.com/MarkMLl?tab=repositories

VisualLab

  • Sr. Member
  • ****
  • Posts: 466
Re: Editing wiki.
« Reply #7 on: September 01, 2024, 11:51:07 am »
As a very long term Unix/Linux sysadmin, there is almost no circumstance where its a good idea to run something like Lazarus as root.  If your resulting application MUST be run as root, its quite easy to use a script or other tricks to give it (and only it) root access but please don't run gui apps that make extensive changes to its own files as root. Ever.  Worthwhile looking at what can be done with the sudo command for example.

Totally agree if you're administering a server, router or something similar. Although using RPi as a server is inefficient (unless it is a private server for simple applications), it is a private matter for the user. However, RPi is very often used to implement various projects combining software and electronics (automation, measurements, etc.).

However, if someone uses RPi to work with electronics (especially as a hobby), then constantly "typing spells" in the console is a pure waste of time. It is common knowledge that work (including hobby work) consisting in creating a prototype and experimenting with it requires many changes, corrections in the source code, compilation cycles, continuous runs, etc. Then you should definitely use the root account (and if possible, with GUI). Unfortunately, "Linux chekists" are determined to make Linux disgusting for ordinary people. Laboriously typing the same "strings of texts" 99999 times is idiotic (even by recalling commands from the history). What was sufficient in the 1970s and 1980s has long ceased to be useful and sensible. 40 years have passed since 1984 - that's half a human life! GUI (and other facilities) were invented to make people's work more efficient. "For God's sake", it's the 21st century!
« Last Edit: September 01, 2024, 11:53:29 am by VisualLab »

MarkMLl

  • Hero Member
  • *****
  • Posts: 7649
Re: Editing wiki.
« Reply #8 on: September 01, 2024, 12:57:49 pm »
Then you should definitely use the root account (and if possible, with GUI).

No, you most definitely should not.

A program with root privilege can read the content of the /etc/shadow file, and send it away to be cracked. It can terminate any other process, and it can listen instead to any low-numbered TCP or UDP port hence sniff credentials etc.

If a program uses an API that /demands/ root access, then either the program or the API is doing things wrong.

MarkMLl
MT+86 & Turbo Pascal v1 on CCP/M-86, multitasking with LAN & graphics in 128Kb.
Logitech, TopSpeed & FTL Modula-2 on bare metal (Z80, '286 protected mode).
Pet hate: people who boast about the size and sophistication of their computer.
GitHub repositories: https://github.com/MarkMLl?tab=repositories

Aruna

  • Sr. Member
  • ****
  • Posts: 457
Re: Editing wiki.
« Reply #9 on: September 01, 2024, 01:07:29 pm »
Aruna's advice is good when the existing information is well structured.
Hi Juha, long time no see. It is good to hear from you. I hope you and your son are keeping well.

Full disclosure: That reply was not all my own. I ran the question through chatGPT and tweaked and polished what it generated until I was happy then posted it. ( I do not think I could have come up with that all by myself. It is AI tool to be used with caution and if it helps solve a problem then why not? Most will disagree and some might agree?  )

Thus I suggest a more aggressive stance for Wiki editing than Aruna has.
Lots of information is outdated and the authors have moved on years ago.
If you have a clear vision about how to improve both the information and the structure of pages, please do so.
Yes, it is a good idea to mention it here in forum. Then others can review it and comment.
The Wiki remembers its history. Old data can be restored if things go wrong.
I did not know the wiki remembers it's history and can be restored to a given point in time.
Debian GNU/Linux 11 (bullseye)
https://pascal.chat/

MarkMLl

  • Hero Member
  • *****
  • Posts: 7649
Re: Editing wiki.
« Reply #10 on: September 01, 2024, 01:23:49 pm »
I did not know the wiki remembers it's history and can be restored to a given point in time.

Look at the tabs/links near the top of each page, hence https://wiki.freepascal.org/index.php?title=Main_Page&action=history etc.

Basically, the dominant wiki servers store changes/versions in a database, which can be "mined" for all sorts of things hence see e.g. https://web.archive.org/web/20060824210044/http://alumni.media.mit.edu/~fviegas/papers/history_flow.pdf (if nothing else, look at the pictures).

MarkMLl
MT+86 & Turbo Pascal v1 on CCP/M-86, multitasking with LAN & graphics in 128Kb.
Logitech, TopSpeed & FTL Modula-2 on bare metal (Z80, '286 protected mode).
Pet hate: people who boast about the size and sophistication of their computer.
GitHub repositories: https://github.com/MarkMLl?tab=repositories

dbannon

  • Hero Member
  • *****
  • Posts: 3074
    • tomboy-ng, a rewrite of the classic Tomboy
Re: Editing wiki.
« Reply #11 on: September 01, 2024, 02:30:48 pm »

Putting aside the security issues, the problem with running, eg, Lazarus, as root is Lazarus is constantly building new files and replacing existing ones (source code, object files, ppu, binaries...). If it does that as root, the new files are owned (and protected) by root.  An ordinary user cannot remove or update them.

Lazarus makes no allowances for this situation, it assumes its files are its files. Next time you run Lazarus, it fails to update the files it expects to be able to update, it does not test to see if it has permission, why should it ?  So, it crashes, or maybe worse, continues to use the old file. In either case, because Lazarus, quite sensibly does not expect anything this silly to happen, it cannot warn or advise the user. In the end, they will probably have to remove and reinstall Lazarus. Something Windows users are used to, not so *nix users. But some package managers refuse to remove files, in root space, not owned by root. So, even thats hard.

But yes, the security concerns are a factor too. In this brave new world we live in, everyone, even VisualLab, have a responsibility to deny the bad guys every, and I mean every, access point.

In terms of spells, rubbish. Most distros these days have sudo, Rasberry Pi OS, does not even require a root password, just the 'sudo '. The important thing here is that you are running your application as root, not the edit, compile process, not the project and IDE settings.

And, again, I question even the need to run the developing app as root, *nix has an easy to understand access controls. If you cannot handle them, you probably do believe in spells !

Davo
Lazarus 3, Linux (and reluctantly Win10/11, OSX Monterey)
My Project - https://github.com/tomboy-notes/tomboy-ng and my github - https://github.com/davidbannon

Aruna

  • Sr. Member
  • ****
  • Posts: 457
Re: Editing wiki.
« Reply #12 on: September 01, 2024, 02:35:53 pm »
I did not know the wiki remembers it's history and can be restored to a given point in time.

Look at the tabs/links near the top of each page, hence https://wiki.freepascal.org/index.php?title=Main_Page&action=history etc.
Ah, I see. Very nice the way it keeps track.

Basically, the dominant wiki servers store changes/versions in a database, which can be "mined" for all sorts of things hence see e.g. https://web.archive.org/web/20060824210044/http://alumni.media.mit.edu/~fviegas/papers/history_flow.pdf (if nothing else, look at the pictures).
Impressive, the authors of the paper are from MIT and IBM research, and at the top it says 'CHI 2004 ׀ Paper 24-29 April ׀ Vienna, Austria' Would you know what CHI stands for?
 





Debian GNU/Linux 11 (bullseye)
https://pascal.chat/

MarkMLl

  • Hero Member
  • *****
  • Posts: 7649
Re: Editing wiki.
« Reply #13 on: September 01, 2024, 03:07:01 pm »
I think it's fair to add that collaborative editing very much predates wikis, it fact was very much part of TBL's concept of the WWW which was of course intended primarily for academics. I can't remember the detail but early HTTP had a verb(?) for uploading an entire document rather than having to use FTP etc., and Sun actually extended it with a "patch" verb which could very much be considered a predecessor of the way wikis etc. work today.

Larry Wall also describes trying to modify the NNTP/NNRP to do something similar, but having BTDT (and in particular having suffered later versions of INN) I can attest that that attempt would have been painful.

Impressive, the authors of the paper are from MIT and IBM research, and at the top it says 'CHI 2004 ׀ Paper 24-29 April ׀ Vienna, Austria' Would you know what CHI stands for?

Something like "Computers and Human Interaction"... http://www.chi2004.org/ via Google.

There's at least one related live project, albeit not quite as pretty.

MarkMLl
« Last Edit: September 01, 2024, 03:29:36 pm by MarkMLl »
MT+86 & Turbo Pascal v1 on CCP/M-86, multitasking with LAN & graphics in 128Kb.
Logitech, TopSpeed & FTL Modula-2 on bare metal (Z80, '286 protected mode).
Pet hate: people who boast about the size and sophistication of their computer.
GitHub repositories: https://github.com/MarkMLl?tab=repositories

 

TinyPortal © 2005-2018