1. [docs] How do I use Github?
- Posted by _tom (admin) Sep 26, 2019
- 1759 views
I can not find a small easy to use Github client.
How do I upload a revised file to Github?
_tom
2. Re: [docs] How do I use Github?
- Posted by Icy_Viking Sep 26, 2019
- 1746 views
I can not find a small easy to use Github client.
How do I upload a revised file to Github?
_tom
If you're on Windows, you can use Windows for Github or Visual Studio has a plugin for using Github. If you already have repository on Github, then you can go into the project and select the file you want to edit or upload and click on the upload button to upload a revised file.
3. Re: [docs] How do I use Github?
- Posted by _tom (admin) Sep 26, 2019
- 1737 views
If you're on Windows, you can use Windows for Github or Visual Studio has a plugin for using Github.
My computers do no run Windows.
If you already have repository on Github, then you can go into the project and select the file you want to edit or upload and click on the upload button to upload a revised file.
Tried and it works.
I am sure that Greg will get angry with me for trying (sorry). I uploaded a revised "datetime.e" with the result that Github did not track individual changes. It just shows a whole file swap.
I am sure that I am abusing my god powers in messing with the Euphoria repository...
_tom
4. Re: [docs] How do I use Github?
- Posted by euphoric (admin) Sep 26, 2019
- 1794 views
I uploaded a revised "datetime.e" with the result that Github did not track individual changes. It just shows a whole file swap.
Hey, _tom,
If you'll notice in the commit log, I had already handled datetime.e days ago.
Not sure what you uploaded, but this is why we need to get synchronized with the proper work flow, so we're not duplicating effort.
I'm going to try to fix this, but please don't use the file upload commit in the future.
5. Re: [docs] How do I use Github?
- Posted by _tom (admin) Sep 26, 2019
- 1768 views
The question remains. What is the workflow?
_tom
6. Re: [docs] How do I use Github?
- Posted by euphoric (admin) Sep 26, 2019
- 1762 views
The question remains. What is the workflow?
Two methods:
Or
7. Re: [docs] How do I use Github?
- Posted by irv Sep 27, 2019
- 1737 views
The question remains. What is the workflow?
Two methods:
Or
Forking is crazy - there is 100% chance that someone will introduce at least one error into the source, so there will need to be intensive testing before the release. Plus there will be multiple versions of the docs, so someone has to decide which version is the most appropriate and accurate, then merge them all.
Tickets are the only way as long as the misguided idea of trying to produce accurate and useful docs from markup in the source remains the rule. It can't work, and if I had tried that in my former job, I'd have been fired.
Look at the source and see how you have to wade thru the "documentation" to find the actual working code. It's unhelpful, it's so limited that it can never produce modern, attractive and informative documentation, and I don't want to bother supporting the idea any further.
I wonder who made up this rule that "here docs" were the only acceptable option and no others should be considered?
8. Re: [docs] How do I use Github?
- Posted by _tom (admin) Sep 27, 2019
- 1731 views
The question remains. What is the workflow?
Two methods:
Or
Forking is crazy - there is 100% chance that someone will introduce at least one error into the source, so there will need to be intensive testing before the release. Plus there will be multiple versions of the docs, so someone has to decide which version is the most appropriate and accurate, then merge them all.
Tickets are the only way as long as the misguided idea of trying to produce accurate and useful docs from markup in the source remains the rule. It can't work, and if I had tried that in my former job, I'd have been fired.
Look at the source and see how you have to wade thru the "documentation" to find the actual working code. It's unhelpful, it's so limited that it can never produce modern, attractive and informative documentation, and I don't want to bother supporting the idea any further.
I wonder who made up this rule that "here docs" were the only acceptable option and no others should be considered?
Rant follows.
Forking is crazy.
Tickets is crazy
Here docs is crazy.
Test case is "datetime.e"
Datetime issues
UTC has replace GTM
The interval "Date" makes no sense for add) and subtract) sub-programs.
Many examples, still, do not satisfy basic cut-paste-run.
The clarity of explanations could be improved.
I want hashtags for every topic to make writing documentation easier, to make searching easier, and to make indexing documentation easier.
Multiple authors will never create uniform formatting--one person will ultimately have to go over all of the docs.
Documentation has to be re-written continuously, not written.
Fork
I have a fork on my computer that I can not merge into my Github repository fork of the true Euphoria; which I turn I cannot merge into the true Euphoria source. Irv can not comment or edit my fork.
I am getting the impression that Github is not intended to work nicely with Linux. Using the Windows operating system is too difficult for me (I think Windows is getting to a billion installs; that's a billion people smarter than me.)
Tickets
There are a bunch of tickets marked "fixed" which I do not consider to be fixed. Do I enter a ticket to report these tickets? Even if I wanted to, there is no mechanism for me to fix a ticket.
Here Docs
Greatest fear in writing docs is harming the actual source-code. Editing docs in source-code is not pleasant because you have to navigate past all of the source-code to get to the documentation. Editing " - - " lines of source-code slows down the process of writing documentation. Source-code is going to get bloated with documentation and examples. I can not edit the source-code to create documentation because I do not (yet) get along with Github. Github does not like Linux?--I am too feeble to figure out if this is true.
Wiki/Pastey
No way coerce them to work for editing docs. Maybe in the future Greg will invent something.
As Mark Twain, and others, have stated "I would have written a shorter reply if I had the time."
_tom
9. Re: [docs] How do I use Github?
- Posted by euphoric (admin) Sep 27, 2019
- 1755 views
Forking is crazy - there is 100% chance that someone will introduce at least one error into the source, so there will need to be intensive testing before the release.
The need for testing is true no matter who is committing updated source. But I see your point. That's why having a few devs working off other people's submissions is probably the best way (for now).
Tickets are the only way as long as the misguided idea of trying to produce accurate and useful docs from markup in the source remains the rule.
Please bear with us as we transition to a new method. This is the old way, adopted probably because it's standard practice in a lot of projects. We can transition to a new model, but for now we're having to use the old way. I think Greg is the only dev working on a release, so anything you can do to help and not hinder the work is appreciated.
Look at the source and see how you have to wade thru the "documentation" to find the actual working code.
I have, and it was very easy to manage. As long as the tickets are comprehensive in the request, fixing the docs should be relatively straightforward and easy (but maybe not quick, since only a couple of people with day jobs are working on them).
It's unhelpful, it's so limited that it can never produce modern, attractive and informative documentation, and I don't want to bother supporting the idea any further.
And that's fine. You don't have to. It's just that your help will make the transition quicker and easier. We're all having to suffer at the moment, and if we want an up-to-date, modern Euphoria, this is just the way it's going to be for now.
I wonder who made up this rule that "here docs" were the only acceptable option and no others should be considered?
While this is irrelevant, I think it is a common practice. According to this Wikipedia article, "Software documentation,"
Often, tools such as Doxygen, NDoc, Visual Expert, Javadoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText, or Universal Report can be used to auto-generate the code documents—that is, they extract the comments and software contracts, where available, from the source code and create reference manuals in such forms as text or HTML files.
10. Re: [docs] How do I use Github?
- Posted by euphoric (admin) Sep 27, 2019
- 1730 views
Many examples, still, do not satisfy basic cut-paste-run.
The clarity of explanations could be improved.
Make a ticket with examples/clear explanations so I can easily cut/paste it into the docs.
I want hashtags for every topic to make writing documentation easier, to make searching easier, and to make indexing documentation easier.
I'm not sure categorizing with hashtags is useful in documentation, but I could be wrong! Can you expand on this a bit?
Multiple authors will never create uniform formatting--one person will ultimately have to go over all of the docs.
Documentation has to be re-written continuously, not written.
This is true.
I have a fork on my computer that I can not merge into my Github repository fork of the true Euphoria; which I turn I cannot merge into the true Euphoria source.
This is just a matter of learning git. I'm doing all of that. I have a fork. I push changes. I then make a pull request and merge those changes into Euphoria/euphoria. It's smooth and easy, but not simple and quick.
There are a bunch of tickets marked "fixed" which I do not consider to be fixed. Do I enter a ticket to report these tickets?
I'm not sure what the standard operating procedure is for this. Maybe Greg can comment.
11. Re: [docs] How do I use Github?
- Posted by ghaberek (admin) Sep 27, 2019
- 1723 views
Forking is crazy
the misguided idea
It can't work
I'd have been fired
It's unhelpful
it can never produce
I don't want to bother
I wonder who made up this rule
I'm really getting sick of your bitching and nay-saying here, Irv. It's time to put up or shut up.
Either start contributing to the docs as they are or present an immediate and useful solution to the problem.
In the meantime, I'm going to continue work on what I've planned and I'll not be addressing another word about the state of the documentation until after I publish a release.
-Greg
12. Re: [docs] How do I use Github?
- Posted by _tom (admin) Sep 27, 2019
- 1731 views
Thanks Greg for the work you are putting into Euphoria. It is all greatly appreciated.
...
Either start contributing to the docs as they are or present an immediate and useful solution to the problem.
It is reasonable to say that all of my experiments have failed.
In the meantime, I'm going to continue work on what I've planned and I'll not be addressing another word about the state of the documentation until after I publish a release.
-Greg
Fair solution. Get a release out. Then, I will review the published docs, make comments, and send tickets into the system. Then we put a +0.1 plus release. Keep iterating until things look better.
The model of "huff and puff" and "willy nilly" is too stressful.
_tom
13. Re: [docs] How do I use Github?
- Posted by irv Oct 03, 2019
- 1649 views
Either start contributing to the docs as they are or present an immediate and useful solution to the problem.
So, you haven't noticed that I have contributed nearly two full pages of tickets?
Some of the contributions have been applied, others rejected, perhaps for good reason, but in no case have my suggestions been posted so that users can suggest more appropriate demos or find mistakes.
I've tried to do things the way you think they should be done. I don't see it working, because there are are only 2 or 3 people who have bothered to write even one ticket. I'm not going to go thru the entire documentation by myself.
So I will take your suggestion and just shut up and go away.
14. Re: [docs] How do I use Github?
- Posted by ChrisB (moderator) Oct 03, 2019
- 1631 views
FFS you lot, this is so incredibly frustratimg. Start acting like grown ups instead of spoilt children!