Change solr/lucene Readme file format

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Change solr/lucene Readme file format

Man with No Name
Hey folks,
I have been looking into the solr/lucene source code, and the first thing caught my eye was the different Readme files. All the files had different file and text format. What do you guys think about making all the readmes to markdown file rather than text files, and a standard template?


--
Regards:
Pinkesh Sharma                                                    
Reply | Threaded
Open this post in threaded view
|

Re: Change solr/lucene Readme file format

Erick Erickson
Personally I’d make them text files. The last thing I want to do is make reading/updating these have a barrier to entry. We should save formatting for the ref guide and/or Wiki.

Best,
Erick

> On Nov 10, 2019, at 1:01 AM, Man with No Name <[hidden email]> wrote:
>
> Hey folks,
> I have been looking into the solr/lucene source code, and the first thing caught my eye was the different Readme files. All the files had different file and text format. What do you guys think about making all the readmes to markdown file rather than text files, and a standard template?
>
>
> --
> Regards:
> Pinkesh Sharma                                                    


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Change solr/lucene Readme file format

Marcus Eagan
Most README files in contemporary open source projects are Markdown because of the formatting features. I personally favor convention over ease of use in this case. 

Marcus Eagan

On Sun, Nov 10, 2019, 8:58 AM Erick Erickson <[hidden email]> wrote:
Personally I’d make them text files. The last thing I want to do is make reading/updating these have a barrier to entry. We should save formatting for the ref guide and/or Wiki.

Best,
Erick

> On Nov 10, 2019, at 1:01 AM, Man with No Name <[hidden email]> wrote:
>
> Hey folks,
> I have been looking into the solr/lucene source code, and the first thing caught my eye was the different Readme files. All the files had different file and text format. What do you guys think about making all the readmes to markdown file rather than text files, and a standard template?
>
>
> --
> Regards:
> Pinkesh Sharma                                                     


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Change solr/lucene Readme file format

Uwe Schindler
Hi,

When building the documentation (ant documentation), all readme files included in the documentation are parsed as markdown (see flexmark task in ant) and converted to html. This works well, although not everything is markdown. If you have a plain readme file it would still parse as valid markdown and HTML output looks fine, so Erik's problem with markdown isn't one.

Uwe

Am November 10, 2019 4:00:21 PM UTC schrieb Marcus Eagan <[hidden email]>:
Most README files in contemporary open source projects are Markdown because of the formatting features. I personally favor convention over ease of use in this case. 

Marcus Eagan

On Sun, Nov 10, 2019, 8:58 AM Erick Erickson <[hidden email]> wrote:
Personally I’d make them text files. The last thing I want to do is make reading/updating these have a barrier to entry. We should save formatting for the ref guide and/or Wiki.

Best,
Erick

> On Nov 10, 2019, at 1:01 AM, Man with No Name <[hidden email]> wrote:
>
> Hey folks,
> I have been looking into the solr/lucene source code, and the first thing caught my eye was the different Readme files. All the files had different file and text format. What do you guys think about making all the readmes to markdown file rather than text files, and a standard template?
>
>
> --
> Regards:
> Pinkesh Sharma                                                     


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


--
Uwe Schindler
Achterdiek 19, 28357 Bremen
https://www.thetaphi.de
Reply | Threaded
Open this post in threaded view
|

Re: Change solr/lucene Readme file format

Man with No Name
Hey guys,
I have created a PR on this, please have a look to see if that's helpful.

Thanks:
Pinkesh Sharma

On Sun, Nov 10, 2019 at 11:29 AM Uwe Schindler <[hidden email]> wrote:
Hi,

When building the documentation (ant documentation), all readme files included in the documentation are parsed as markdown (see flexmark task in ant) and converted to html. This works well, although not everything is markdown. If you have a plain readme file it would still parse as valid markdown and HTML output looks fine, so Erik's problem with markdown isn't one.

Uwe

Am November 10, 2019 4:00:21 PM UTC schrieb Marcus Eagan <[hidden email]>:
Most README files in contemporary open source projects are Markdown because of the formatting features. I personally favor convention over ease of use in this case. 

Marcus Eagan

On Sun, Nov 10, 2019, 8:58 AM Erick Erickson <[hidden email]> wrote:
Personally I’d make them text files. The last thing I want to do is make reading/updating these have a barrier to entry. We should save formatting for the ref guide and/or Wiki.

Best,
Erick

> On Nov 10, 2019, at 1:01 AM, Man with No Name <[hidden email]> wrote:
>
> Hey folks,
> I have been looking into the solr/lucene source code, and the first thing caught my eye was the different Readme files. All the files had different file and text format. What do you guys think about making all the readmes to markdown file rather than text files, and a standard template?
>
>
> --
> Regards:
> Pinkesh Sharma                                                     


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


--
Uwe Schindler
Achterdiek 19, 28357 Bremen
https://www.thetaphi.de


--
Regards:
Pinkesh Sharma                                                    
Reply | Threaded
Open this post in threaded view
|

Re: Change solr/lucene Readme file format

Doug Turnbull
I think this got lost in the holidays. I wanted to bump this contribution, as I feel markdown is pretty standard format for readmes that devs are expecting these days. (And the files were close to markdown anyway.)

Or if the project doesn't want this contribution, I feel we should at least let Pinkesh (with his 1st contribution) that this isn't something the project wants, and close the PR

Best!
-Doug

On Thu, Nov 14, 2019 at 12:51 AM Man with No Name <[hidden email]> wrote:
Hey guys,
I have created a PR on this, please have a look to see if that's helpful.

Thanks:
Pinkesh Sharma

On Sun, Nov 10, 2019 at 11:29 AM Uwe Schindler <[hidden email]> wrote:
Hi,

When building the documentation (ant documentation), all readme files included in the documentation are parsed as markdown (see flexmark task in ant) and converted to html. This works well, although not everything is markdown. If you have a plain readme file it would still parse as valid markdown and HTML output looks fine, so Erik's problem with markdown isn't one.

Uwe

Am November 10, 2019 4:00:21 PM UTC schrieb Marcus Eagan <[hidden email]>:
Most README files in contemporary open source projects are Markdown because of the formatting features. I personally favor convention over ease of use in this case. 

Marcus Eagan

On Sun, Nov 10, 2019, 8:58 AM Erick Erickson <[hidden email]> wrote:
Personally I’d make them text files. The last thing I want to do is make reading/updating these have a barrier to entry. We should save formatting for the ref guide and/or Wiki.

Best,
Erick

> On Nov 10, 2019, at 1:01 AM, Man with No Name <[hidden email]> wrote:
>
> Hey folks,
> I have been looking into the solr/lucene source code, and the first thing caught my eye was the different Readme files. All the files had different file and text format. What do you guys think about making all the readmes to markdown file rather than text files, and a standard template?
>
>
> --
> Regards:
> Pinkesh Sharma                                                     


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


--
Uwe Schindler
Achterdiek 19, 28357 Bremen
https://www.thetaphi.de


--
Regards:
Pinkesh Sharma                                                    


--
Doug Turnbull | CTO | OpenSource Connections, LLC | 240.476.9983 
Author: Relevant Search
This e-mail and all contents, including attachments, is considered to be Company Confidential unless explicitly stated otherwise, regardless of whether attachments are marked as such.
Reply | Threaded
Open this post in threaded view
|

Re: Change solr/lucene Readme file format

Houston Putman
Markdown is very standard at this point and I think the barrier to entry is very small, at least much smaller than asciidoc, which is used for the ref guide.

+1 on this for me.

On Wed, Jan 22, 2020 at 9:43 AM Doug Turnbull <[hidden email]> wrote:
I think this got lost in the holidays. I wanted to bump this contribution, as I feel markdown is pretty standard format for readmes that devs are expecting these days. (And the files were close to markdown anyway.)

Or if the project doesn't want this contribution, I feel we should at least let Pinkesh (with his 1st contribution) that this isn't something the project wants, and close the PR

Best!
-Doug

On Thu, Nov 14, 2019 at 12:51 AM Man with No Name <[hidden email]> wrote:
Hey guys,
I have created a PR on this, please have a look to see if that's helpful.

Thanks:
Pinkesh Sharma

On Sun, Nov 10, 2019 at 11:29 AM Uwe Schindler <[hidden email]> wrote:
Hi,

When building the documentation (ant documentation), all readme files included in the documentation are parsed as markdown (see flexmark task in ant) and converted to html. This works well, although not everything is markdown. If you have a plain readme file it would still parse as valid markdown and HTML output looks fine, so Erik's problem with markdown isn't one.

Uwe

Am November 10, 2019 4:00:21 PM UTC schrieb Marcus Eagan <[hidden email]>:
Most README files in contemporary open source projects are Markdown because of the formatting features. I personally favor convention over ease of use in this case. 

Marcus Eagan

On Sun, Nov 10, 2019, 8:58 AM Erick Erickson <[hidden email]> wrote:
Personally I’d make them text files. The last thing I want to do is make reading/updating these have a barrier to entry. We should save formatting for the ref guide and/or Wiki.

Best,
Erick

> On Nov 10, 2019, at 1:01 AM, Man with No Name <[hidden email]> wrote:
>
> Hey folks,
> I have been looking into the solr/lucene source code, and the first thing caught my eye was the different Readme files. All the files had different file and text format. What do you guys think about making all the readmes to markdown file rather than text files, and a standard template?
>
>
> --
> Regards:
> Pinkesh Sharma                                                     


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


--
Uwe Schindler
Achterdiek 19, 28357 Bremen
https://www.thetaphi.de


--
Regards:
Pinkesh Sharma                                                    


--
Doug Turnbull | CTO | OpenSource Connections, LLC | 240.476.9983 
Author: Relevant Search
This e-mail and all contents, including attachments, is considered to be Company Confidential unless explicitly stated otherwise, regardless of whether attachments are marked as such.
Reply | Threaded
Open this post in threaded view
|

Re: Change solr/lucene Readme file format

Jan Høydahl / Cominvent
I added some review comments on the PR: https://github.com/apache/lucene-solr/pull/908 as some of the converted files were not really markdown compliant or did not look good in GitHub. Let’s hope the contributor is still around to address this.

Agree that we should pay special attention to first time contributors! Perhaps a weekly email with a list of PRs from first timers?

Jan Høydahl

22. jan. 2020 kl. 16:11 skrev Houston Putman <[hidden email]>:


Markdown is very standard at this point and I think the barrier to entry is very small, at least much smaller than asciidoc, which is used for the ref guide.

+1 on this for me.

On Wed, Jan 22, 2020 at 9:43 AM Doug Turnbull <[hidden email]> wrote:
I think this got lost in the holidays. I wanted to bump this contribution, as I feel markdown is pretty standard format for readmes that devs are expecting these days. (And the files were close to markdown anyway.)

Or if the project doesn't want this contribution, I feel we should at least let Pinkesh (with his 1st contribution) that this isn't something the project wants, and close the PR

Best!
-Doug

On Thu, Nov 14, 2019 at 12:51 AM Man with No Name <[hidden email]> wrote:
Hey guys,
I have created a PR on this, please have a look to see if that's helpful.

Thanks:
Pinkesh Sharma

On Sun, Nov 10, 2019 at 11:29 AM Uwe Schindler <[hidden email]> wrote:
Hi,

When building the documentation (ant documentation), all readme files included in the documentation are parsed as markdown (see flexmark task in ant) and converted to html. This works well, although not everything is markdown. If you have a plain readme file it would still parse as valid markdown and HTML output looks fine, so Erik's problem with markdown isn't one.

Uwe

Am November 10, 2019 4:00:21 PM UTC schrieb Marcus Eagan <[hidden email]>:
Most README files in contemporary open source projects are Markdown because of the formatting features. I personally favor convention over ease of use in this case. 

Marcus Eagan

On Sun, Nov 10, 2019, 8:58 AM Erick Erickson <[hidden email]> wrote:
Personally I’d make them text files. The last thing I want to do is make reading/updating these have a barrier to entry. We should save formatting for the ref guide and/or Wiki.

Best,
Erick

> On Nov 10, 2019, at 1:01 AM, Man with No Name <[hidden email]> wrote:
>
> Hey folks,
> I have been looking into the solr/lucene source code, and the first thing caught my eye was the different Readme files. All the files had different file and text format. What do you guys think about making all the readmes to markdown file rather than text files, and a standard template?
>
>
> --
> Regards:
> Pinkesh Sharma                                                     


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


--
Uwe Schindler
Achterdiek 19, 28357 Bremen
https://www.thetaphi.de


--
Regards:
Pinkesh Sharma                                                    


--
Doug Turnbull | CTO | OpenSource Connections, LLC | 240.476.9983 
Author: Relevant Search
This e-mail and all contents, including attachments, is considered to be Company Confidential unless explicitly stated otherwise, regardless of whether attachments are marked as such.
Reply | Threaded
Open this post in threaded view
|

Re: Change solr/lucene Readme file format

Jason Gerlowski
> Perhaps a weekly email with a list of PRs from first timers?

+1.  Would be a helpful nudge for committers to pay attention to other
contributors.

On Thu, Jan 23, 2020 at 4:46 AM Jan Høydahl <[hidden email]> wrote:

>
> I added some review comments on the PR: https://github.com/apache/lucene-solr/pull/908 as some of the converted files were not really markdown compliant or did not look good in GitHub. Let’s hope the contributor is still around to address this.
>
> Agree that we should pay special attention to first time contributors! Perhaps a weekly email with a list of PRs from first timers?
>
> Jan Høydahl
>
> 22. jan. 2020 kl. 16:11 skrev Houston Putman <[hidden email]>:
>
> 
> Markdown is very standard at this point and I think the barrier to entry is very small, at least much smaller than asciidoc, which is used for the ref guide.
>
> +1 on this for me.
>
> On Wed, Jan 22, 2020 at 9:43 AM Doug Turnbull <[hidden email]> wrote:
>>
>> I think this got lost in the holidays. I wanted to bump this contribution, as I feel markdown is pretty standard format for readmes that devs are expecting these days. (And the files were close to markdown anyway.)
>>
>> Or if the project doesn't want this contribution, I feel we should at least let Pinkesh (with his 1st contribution) that this isn't something the project wants, and close the PR
>>
>> Best!
>> -Doug
>>
>> On Thu, Nov 14, 2019 at 12:51 AM Man with No Name <[hidden email]> wrote:
>>>
>>> Hey guys,
>>> I have created a PR on this, please have a look to see if that's helpful.
>>>
>>> Thanks:
>>> Pinkesh Sharma
>>>
>>> On Sun, Nov 10, 2019 at 11:29 AM Uwe Schindler <[hidden email]> wrote:
>>>>
>>>> Hi,
>>>>
>>>> When building the documentation (ant documentation), all readme files included in the documentation are parsed as markdown (see flexmark task in ant) and converted to html. This works well, although not everything is markdown. If you have a plain readme file it would still parse as valid markdown and HTML output looks fine, so Erik's problem with markdown isn't one.
>>>>
>>>> Uwe
>>>>
>>>> Am November 10, 2019 4:00:21 PM UTC schrieb Marcus Eagan <[hidden email]>:
>>>>>
>>>>> Most README files in contemporary open source projects are Markdown because of the formatting features. I personally favor convention over ease of use in this case.
>>>>>
>>>>> Marcus Eagan
>>>>>
>>>>> On Sun, Nov 10, 2019, 8:58 AM Erick Erickson <[hidden email]> wrote:
>>>>>>
>>>>>> Personally I’d make them text files. The last thing I want to do is make reading/updating these have a barrier to entry. We should save formatting for the ref guide and/or Wiki.
>>>>>>
>>>>>> Best,
>>>>>> Erick
>>>>>>
>>>>>> > On Nov 10, 2019, at 1:01 AM, Man with No Name <[hidden email]> wrote:
>>>>>> >
>>>>>> > Hey folks,
>>>>>> > I have been looking into the solr/lucene source code, and the first thing caught my eye was the different Readme files. All the files had different file and text format. What do you guys think about making all the readmes to markdown file rather than text files, and a standard template?
>>>>>> >
>>>>>> >
>>>>>> > --
>>>>>> > Regards:
>>>>>> > Pinkesh Sharma
>>>>>>
>>>>>>
>>>>>> ---------------------------------------------------------------------
>>>>>> To unsubscribe, e-mail: [hidden email]
>>>>>> For additional commands, e-mail: [hidden email]
>>>>>>
>>>>
>>>> --
>>>> Uwe Schindler
>>>> Achterdiek 19, 28357 Bremen
>>>> https://www.thetaphi.de
>>>
>>>
>>>
>>> --
>>> Regards:
>>> Pinkesh Sharma
>>
>>
>>
>> --
>> Doug Turnbull | CTO | OpenSource Connections, LLC | 240.476.9983
>> Author: Relevant Search
>> This e-mail and all contents, including attachments, is considered to be Company Confidential unless explicitly stated otherwise, regardless of whether attachments are marked as such.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]