Fixing up the Contribute.md file

[bgirardot]

Edit: I mean the CONTRIBUTING.md file.

I think I see how I can make the contribution page a little more clear. I am in the process of editing it up and will issue a pull request for my changes when I am done.

https://github.com/hotosm/learnosm/blob/gh-pages/CONTRIBUTING.md

If anyone else is working on this file, please let me know here. I should have my version of this file done in about a day.

Regards,
Blake

[bgirardot]

If someone who knows the actual workflow could please review my version of the workflow, based on my understanding of the workflow and the activities done by the Github helper I would really appreciate it.

I have edited the page down to and including the "text for in translation header" section.

https://github.com/bgirardot/learnosm/blob/gh-pages/CONTRIBUTING.md

[Nick-Tallguy]

@bgirardot

Blake,
I think you have made the instructions clearer, but;
a/. there will be a delay before the document becomes available for the translator to work on - Github helper may not have 'write access' to hotosm/learnosm, in which case the github helper creates the file for translation, adds the header, saves it in the language folder, and then submits a pull request. When the pull request is actioned the file becomes available in hotosm/learnosm

1. (Section 6) Surely the translator can issue pull requests as they progress - I think github deals with these as 'patches'. The 'owner' can action the pull requests at intervals and the translated section appears on the site. We don't lose anything even if only a couple of sentences are translated, and that may be just the help that someone needs. If you look at the current issues list you will find there are some translations (2 I think) that have been in progress for months - I don't think anything has appeared on the site yet, which does nothing to enthuse the translator.
2. (Section 7) I think the obtaining of screenshots should be the responsibility of the github helper - they will probably need altering from the original (file size reduction etc) and I prefer to see the translation process as easy as possible. The github helper will / should have more understanding of what is needed. I would hope that a bit of collaboration could take place if there are language problems.

[bgirardot]

I don't know Nick, I think there needs to be some clarification on the
actual process then:

a/. there will be a delay before the document becomes available for the
translator to work on - Github helper may not have 'write access' to
hotosm/learnosm, in which case the github helper creates the file for
translation, adds the header, saves it in the language folder, and then
submits a pull request. When the pull request is actioned the file
becomes available in hotosm/learnosm

This makes no sense to me. To me, the point of a github helper is that
they have write access to the learnosm repository.

Otherwise, there is no need for a github helper at this step, they are
just forking the repo, copying the file, adding the header and then
asking someone else to merge the pull request to add the file into the
learnosm repo.

The translator can do all that without the need for any 2nd party
"github helper" at all.

A github helper who can't alter the main learnosm repo is just adding a
time delay to the whole process and is sort of confusing, now we have 2
people making pull requests for translating 1 file.

1. (Section 6) Surely the translator can issue pull requests as they
   progress - I think github deals with these as 'patches'. The 'owner'
   can action the pull requests at intervals and the translated section
   appears on the site. We don't lose anything even if only a couple of
   sentences are translated, and that may be just the help that someone
   needs. If you look at the current issues list you will find there
   are some translations (2 I think) that have been in progress for
   months - I don't think anything has appeared on the site yet, which
   does nothing to enthuse the translator.

I agree with the latter half of this item, but the first half is not how
I understand github to work and might need additional testing using the
built in github file editing facilities.

The tool creates a fork and a new branch in that fork, you only issue 1
pull request for a branch, any changes to that branch automatically
update the pull request so you would not need to make additional pull
requests for that branch*.

Once you merge in any changes from a pull requests I am not sure what
happens next. I think it closes the pull request and I am not sure how
additional changes to the branch the pull request was for are handled.
that might be where you would need to make another pull request to
re-open the original pull request, or maybe you need to create another
branch to make another pull request.

1. (Section 7) I think the obtaining of screenshots should be the
   responsibility of the github helper - they will probably need
   altering from the original (file size reduction etc) and I prefer to
   see the translation process as easy as possible. The github helper
   will / should have more understanding of what is needed.

I disagree, the person who is making the translation understand the
language and can more easily use the software in the translation target
language to get the screen shots.

there is no way as a github helper I am going to be able to use JOSM in
Korean to get screen shots, I don't even have the korean language pack
on my machine (or any other language packs for that matter).

My view is github helpers are there to help with github technicalities
like putting images in the right folder (again, assuming they have write
permission to the repo), creating new folders for new languages, etc.

Translators are there to deal with language issues, like using the
software in the translation target language and getting screen shots.

That is just my opinion though, but I'd keep the language stuff for the
translator, and the github tech to the github helper.

Thank you very much for taking the time to read them over, seems like we
might need some more testing of how the built in tools handle branches
and pull requests and how the github handles merging a branch that is
updated after a merge.

Cheers,
blake

[Nick-Tallguy]

@bgirardot please test on https://github.com/Nick-Tallguy/Testing_learnosm

[althio]

This makes no sense to me. To me, the point of a github helper is that
they have write access to the learnosm repository.

A typical configuration would be:

1. Repo admin with rights on main. Busy guy, cannot help a lot of people.
2. Github helper. Guy with an github account, some technical understanding and limited proficiency on github processes. Available to communicate frequently with would-be translators. Several of them.
3. Translator. Guy knows two languages and a bit of general OSM and HOT --- but has no github account and no technical background.

If you want this to work... I think you should ask:

• only minimal involvement from the admin. Final pull request that is all.
• Github helper acts as a proxy to submit translaters' work
• translator communicates as a human with Github helper and does not need to open a github account.

Channel of communication between translators and github helpers: open mailing list just like [email protected] ...?

Otherwise, there is no need for a github helper at this step, they are
just forking the repo, copying the file, adding the header and then
asking someone else to merge the pull request to add the file into the
learnosm repo.

The translator can do all that without the need for any 2nd party
"github helper" at all.

I disagree. This might be a hurdle for a lot of potential translators.

A github helper who can't alter the main learnosm repo is just adding a
time delay to the whole process and is sort of confusing, now we have 2
people making pull requests for translating 1 file.

Delay for validation of pull requests:

• initial PR for header: delay does not affect the translator work, who can begin right away after agreement with the github helper.
• following PR and final PR: I acknowledge the delay... so be it. Still better than having to deal with only one overbooked admin for everything.

pull requests as they progress - I think github deals with these as 'patches'.
...

not how I understand github to work and might need additional testing using the
built in github file editing facilities.
...

We will have to figure out and the test repo of Nick is certainly just what we need.

1. (Section 7) I think the obtaining of screenshots should be the
   responsibility of the github helper - they will probably need
   altering from the original (file size reduction etc) and I prefer to
   see the translation process as easy as possible. The github helper
   will / should have more understanding of what is needed.

I disagree, the person who is making the translation understand the
language and can more easily use the software in the translation target
language to get the screen shots.

I agree with... both of you.

• initial screenshots using the software: by translator
• these are transferred to the github helper
• altering in a predefined process and moving to github: by github helper.

[bgirardot]

I can't think of a good reason for only 1 person with write access to
the main learnosm repository.

changes are easy to revert and we are not dealing with code where one
missing : can break the entire website.

it is also not like code where the 1 person can review the pull request
to make sure it is right, we are sort of trusting the translator to do a
good job and we are just doing filing duties.

All having 1 person able to change repo accomplishes is making that one
person a bottleneck and creating a lot of work for one person.

• translator communicates as a human with Github helper and does not
  need to open a github account.

In the current workflow the translator will always need a github account
and some github proficiency.

I am not against just sending a translator a file via email and having
them translate it and send it back via email and then having the github
helper create the pull request, but that is a different workflow than we
are suggesting now.

it would probably be easier in the long run to do that though. "hey you
want to help translate? great. which section? Ok, here you go, send us
the stuff back as you translate it with screen shots as needed please."

and then we just take care of it in github.

We will probably spend as much time helping a translator with github as
just doing all the github work ourselves and run the risk of
discouraging the translator as they try and figure out github.

We will have to figure out and the test repo of Nick is certainly just
what we need.

Ya, we just ran through exactly the workflow we are suggesting and it is
confusing on the translator's part, they will need to understand github
a little bit, we will need to make explicit, somewhat step by step
instructions for what they need to do in github. No matter what tools
they use, it is still a process of: fork the main repo, make a branch,
make changes, commit those changes, make a pull request, once merged
make a new branch, make changes, commit, pull request, repeat as needed
until file is translated.

unless of course we ask for just one translated file so we just have one
pull request. but the workflow as outlined with partial translations
going live is confusing to start with for the translator.

even typo corrections follow that fork/branch/edit/pull process, but
usually just one iteration of it, not follow up edits and they don't
need their own copy of the file with the header either.

     1. (Section 7) I think the obtaining of screenshots should be
        the responsibility of the github helper - they will probably
        need altering from the original (file size reduction etc)
        and I prefer to see the translation process as easy as
        possible. The github helper will / should have more
        understanding of what is needed.

I disagree, the person who is making the translation understand the
language and can more easily use the software in the translation target
language to get the screen shots.

I agree with... both of you.

• initial screenshots using the software: by translator
• these are transferred to the github helper
• altering in a predefined process and moving to github: by github
  helper.

Yes, this is what I was thinking, the translator just takes the screen
shots and sends them to the github helper who would make any needed
adjustments to size and would be able to add them in to the repo or
generate a pull request to have them added into the repo.

anyway, it is a bit of a tough nut to crack as we say, but I am leaning
more and more toward just sending them a file and asking them to email
us the translation as they progress.

Thank you althio and Nick for helping me (us) figure this out, I am very
much a person who needs to actually do something once to fully
understand all the details.

Bon courage,
Blake

[althio]

I can't think of a good reason for only 1 person with write access to the main learnosm repository.

Several admins is certainly a good thing.
It lessens bottleneck effect and it becomes less critical when one person is unavailable or definitely gone for the project.

You can merge the roles 'admin' and 'github helper' in some cases then.
But how many admins and how many github helpers do we have or do we need.

In the current workflow the translator will always need a github account and some github proficiency.

That is what I find unsettling in the current workflow.
It boils down to your previous statement:

sort of confusing, now we have 2 people making pull requests for translating 1 file.

Of course if the translator has some github proficiency you can merge 'github helper' and 'translator'... But there is no need for a low-tech workflow then.

So my starting point is translator equals no github at all. I realise this is a different workflow so let me be blunt: I don't like the current workflow as it is. So I want to change it for something as good as possible.

I am not against just sending a translator a file via email and having
them translate it and send it back via email and then having the github
helper create the pull request, but that is a different workflow than we
are suggesting now.

Minor note: no need to send the file to the translated. It is there in English on the website. The translator knows it is there and even that it is lacking translation.
(side note... how about a header for not-translated file)

it would probably be easier in the long run to do that though. "hey you
want to help translate? great. which section? Ok, here you go, send us
the stuff back as you translate it with screen shots as needed please."

• "hey you want to help translate? great. which section? OK, I put a notice to tell others you are on it. Go ahead."
• initial pull request, create the file with header
• "send us the stuff back as you translate it with screen shots as needed please."
• pull requests as we go
• final pull request and remove header

We will probably spend as much time helping a translator with github as just doing all the github work ourselves and run the risk of discouraging the translator as they try and figure out github.

My thoughts exactly.

Ya, we just ran through exactly the workflow we are suggesting and it is confusing on the translator's part, they will need to understand github
...

Please KISS. Absolutely no technical requirements for the translator. I think we can do it this way.

[bgirardot]

Hi,

I just noticed that the "previous workflow" which we still support,
literally has the translator give us their github user ID and then we
(well not us, but jeff I guess) grant them read/write permissions on the
learnosm main repository or some part of it.

If the learnosm main repo is part of an organizational github account
that would allow fine grained control over read/write to specific files
probably. If the learnosm main repo is part of a "personal" account,
which then would only grant read/write on the repo level.

I don't know which one hotosm is, I would guess organizational, but I
don't know and the main github hotosm page does not really say one way
or the other.

But I thought I would point it out as we discuss if a github helper
should have write access to the repo, the previous workflow gave write
access to the translator to at least part of the repo.

Which, actually seems like a pretty good idea if we could give them the
write access to just the file they are supposed to translate.

That would get around all this fork/branch/pull request confusion as
they could just use the github page edit tools directly on the file in
the learnosm main repo.

Maybe we need to adopt those steps from the previous workflow and really
the only change we make is that they use the github file editor
interface instead of the prose.io interface for editing the file.

Just more to think about :)

cheers,
blake

On 12/13/2014 11:14 PM, althio wrote:

This makes no sense to me. To me, the point of a github helper is that
they have write access to the learnosm repository.

A typical configuration would be:

1. Repo admin with rights on main. Busy guy, cannot help a lot of people.
2. Github helper. Guy with an github account, some technical
   understanding and limited proficiency on github processes. Available to
   communicate frequently with would-be translators. Several of them.
3. Translator. Guy knows two languages and a bit of general OSM and HOT
   --- but has no github account and no technical background.

If you want this to work... I think you should ask:

• only minimal involvement from the admin. Final pull request that is all.
• Github helper acts as a proxy to submit translaters' work
• translator communicates as a human with Github helper and does not
  need to open a github account.

Channel of communication between translators and github helpers: open
mailing list just like [email protected] mailto:[email protected] ...?

Otherwise, there is no need for a github helper at this step, they are
just forking the repo, copying the file, adding the header and then
asking someone else to merge the pull request to add the file into the
learnosm repo.

The translator can do all that without the need for any 2nd party
"github helper" at all.

I disagree. This might be a hurdle for a lot of potential translators.

A github helper who can't alter the main learnosm repo is just adding a
time delay to the whole process and is sort of confusing, now we have 2
people making pull requests for translating 1 file.

Delay for validation of pull requests:

• initial PR for header: delay does not affect the translator work,
  who can begin right away after agreement with the github helper.

• following PR and final PR: I acknowledge the delay... so be it.
  Still better than having to deal with only one overbooked admin for
  everything.

  pull requests as they progress - I think github deals with these
  as 'patches'.
  ...
  

  not how I understand github to work and might need additional
  testing using the
  built in github file editing facilities.
  ...

We will have to figure out and the test repo of Nick is certainly just
what we need.

     1. (Section 7) I think the obtaining of screenshots should be
        the responsibility of the github helper - they will probably
        need altering from the original (file size reduction etc)
        and I prefer to see the translation process as easy as
        possible. The github helper will / should have more
        understanding of what is needed.

I disagree, the person who is making the translation understand the
language and can more easily use the software in the translation target
language to get the screen shots.

I agree with... both of you.

• initial screenshots using the software: by translator
• these are transferred to the github helper
• altering in a predefined process and moving to github: by github
  helper.

—
Reply to this email directly or view it on GitHub
#259 (comment).

[wonderchook]

Just wanted to mention there isn't just one person with write access to the main repo. The issue is actually more that only busy people have access to the main repo. Perhaps it makes sense to have some sort of process where people can check each others pull requests. So if one person does a pull request and someone else comments it can be merged.

If others want access and feel comfortable merging let me know. We just want to make sure we don't accidentally introduce problems into the site. Though that happens now sometimes anyway with the current set-up.

[Nick-Tallguy]

@wonderchook
I'm happy to have write access - feel I could manage many of the simpler changes & could ask for help for the bits I'm not happy with.

Nick

[Nick-Tallguy]

Whatever process we come up with for managing translations needs to bear in mind:

We've all got lives outside of this, so nothing should just go to one person as it could lead to long delays - I like the very simple system of sending an email to someone & they translate what you send them, or they send you the translated version of the site. But the email address should be one of the groups ones, so that any one of us could action it.

Personally, my language skills are pretty poor, so I like the idea of having both the English and the other language on the same message, so I can work out where to add the markdown if needed - sort of
English English English English
Translation Translation Translation Translation

• English English English English
  Translation Translation Translation Translation

I now I need to add markdown to the second section as it hasn't got an asterisk at the start. - I need the pattern to recognise where to copy, paste & format.

It's best if there are a few people familiar with the system.

[wonderchook]

@Nick-Tallguy just sent you an invite to have write access.

[althio]

I like the very simple system of sending an email to someone & they translate what you send them, or they send you the translated version of the site.

Blake, Nick, you are right it is certainly best to send a copy of the actual file so that markdown is present. Translator can try to modify in-place.

the email address should be one of the groups ones, so that any one of us could action it.

[email protected] to handle feedback - requests - corrections and translating?

I like the idea of having both the English and the other language on the same message, so I can work out where to add the markdown if needed

I don't know if that can be automated with an existing tool. Or if we have to rely on instructions to translators that they should work block-by-block with alternate languages.

[althio]

@wonderchook
Can I be added with write access? As Nick I would do only merge typos corrections and translations and such simple pull requests. And just comment on the others if more difficult.

[wonderchook]

@althio okay, you've been added and have access once you accept the invite.

[Nick-Tallguy]

I've amended the file slightly, adding an option to email the file for translation.

[Nick-Tallguy]

see #526 and #329 - closing this issue now as contributing.md was updated and tidying is now being covered on the other issues