1. [docs] How do I use Github?

I can not find a small easy to use Github client.

How do I upload a revised file to Github?

_tom

new topic     » topic index » view message » categorize

2. Re: [docs] How do I use Github?

_tom said...

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.

new topic     » goto parent     » topic index » view message » categorize

3. Re: [docs] How do I use Github?

Icy_Viking said...

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.

Icy_Viking said...

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

new topic     » goto parent     » topic index » view message » categorize

4. Re: [docs] How do I use Github?

_tom said...

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.

new topic     » goto parent     » topic index » view message » categorize

5. Re: [docs] How do I use Github?

The question remains. What is the workflow?

_tom

new topic     » goto parent     » topic index » view message » categorize

6. Re: [docs] How do I use Github?

_tom said...

The question remains. What is the workflow?

Two methods:

Fork Euphoria

Or

write tickets

new topic     » goto parent     » topic index » view message » categorize

7. Re: [docs] How do I use Github?

euphoric said...
_tom said...

The question remains. What is the workflow?

Two methods:

Fork Euphoria

Or

write tickets

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?

new topic     » goto parent     » topic index » view message » categorize

8. Re: [docs] How do I use Github?

irv said...
euphoric said...
_tom said...

The question remains. What is the workflow?

Two methods:

Fork Euphoria

Or

write tickets

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

new topic     » goto parent     » topic index » view message » categorize

9. Re: [docs] How do I use Github?

irv said...

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).

irv said...

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.

irv said...

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).

irv said...

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.

irv said...

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,"

Technical documentation embedded in source code
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.

The idea of auto-generating documentation is attractive to programmers for various reasons. For example, because it is extracted from the source code itself (for example, through comments), the programmer can write it while referring to the code, and use the same tools used to create the source code to make the documentation. This makes it much easier to keep the documentation up-to-date.

Of course, a downside is that only programmers can edit this kind of documentation, and it depends on them to refresh the output (for example, by running a cron job to update the documents nightly). Some would characterize this as a pro rather than a con. }}}

new topic     » goto parent     » topic index » view message » categorize

10. Re: [docs] How do I use Github?

_tom said...

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.

_tom said...

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?

_tom said...

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.

_tom said...

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. grin

_tom said...

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.

new topic     » goto parent     » topic index » view message » categorize

11. Re: [docs] How do I use Github?

irv said...

Forking is crazy

irv said...

the misguided idea

irv said...

It can't work

irv said...

I'd have been fired

irv said...

It's unhelpful

irv said...

it can never produce

irv said...

I don't want to bother

irv said...

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

new topic     » goto parent     » topic index » view message » categorize

12. Re: [docs] How do I use Github?

Thanks Greg for the work you are putting into Euphoria. It is all greatly appreciated.


ghaberek said...

...

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.

ghaberek said...

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

new topic     » goto parent     » topic index » view message » categorize

13. Re: [docs] How do I use Github?

ghaberek said...

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.

new topic     » goto parent     » topic index » view message » categorize

14. Re: [docs] How do I use Github?

FFS you lot, this is so incredibly frustratimg. Start acting like grown ups instead of spoilt children!

new topic     » goto parent     » topic index » view message » categorize

Search



Quick Links

User menu

Not signed in.

Misc Menu