Updates to README files for Contributing

159 views
Skip to first unread message

Kevin Sutter

unread,
Feb 20, 2019, 11:25:05 AM2/20/19
to Eclipse MicroProfile
Hi,
Per our discussion on the Google Hangout yesterday, Phillip went ahead and created PRs for many of our component repos to indicate how to get involved and how to contribute...  I greatly appreciate the work that was put in, but I'm not convinced that the README is the best place for this information.  The README should provide a quick, easy overview of the component and how to get started with it.  Leading off with the Contributing Guidelines looks to be a bit much.

As Andy has pointed out in one of the PRs, maybe a better place would be a CONTRIBUTING.md file...  We are supposed to have those in our component repos, but Eclipse doesn't enforce the rule.  If we could create or update the CONTRIBUTING.md file for each affected repo and then maybe just provide a pointer to that file from the README somewhere, maybe that would allow us to still document the processes without cluttering up the README?

Thoughts?
Kevin

Alasdair Nottingham

unread,
Feb 20, 2019, 11:42:25 AM2/20/19
to microp...@googlegroups.com
+1 

Alasdair Nottingham
--
You received this message because you are subscribed to the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/4b158f2b-1cfb-41a1-a184-f5c5033b08e0%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Phillip Krüger

unread,
Feb 20, 2019, 11:50:07 AM2/20/19
to Eclipse MicroProfile
I am easy either way, I can move all to contribute.md and add a link in readme.

Let see how the rest feel.

(I think we should be consistent throughout all projects)

Phillip

Kevin Sutter

unread,
Feb 20, 2019, 12:25:38 PM2/20/19
to Eclipse MicroProfile
Yes, Phillip, consistency is the exact reason I posted to the forum instead of trying to hit everyone of your PRs...  :-)   Thanks!

Phillip Krüger

unread,
Feb 20, 2019, 12:28:54 PM2/20/19
to Eclipse MicroProfile
:) cool. Let see what everyone thinks. If we get no more comments, then let's change to your suggestion, it's cleaner.

Amelia Eiras

unread,
Feb 20, 2019, 1:35:19 PM2/20/19
to Eclipse MicroProfile
+1 on scaling the process on how to welcome a new Microprofiler to help. 

less crowing 100% +1 from me. 

Please keep in mind the creation of the Website Repo, also created after yesterday awesome hangout. 
Using that call feedback, a few issues have been created with focus on the Project page current located in the MP website that needs to be updated as part of the MUST be easy to navigate to enable anyone to contribute to the MP Projects.

  • Project Repo Issues 
  • Website work-doc skeleton (I am on favor of cutting extra steps with this doc and moving forward directly to write issues in the Repo. As a community, we can prioritize the issues in the kaban board for Website waters. 
Cheers, 

Phillip Krüger

unread,
Feb 21, 2019, 9:12:06 AM2/21/19
to Eclipse MicroProfile
Hi All.

So are we happy to rather do a contribute.adoc and link to it from readme.adoc ?
Can I go ahead and make these changes ? (or how long do we wait for more comments?)

Let me know.

Cheers

Kevin Sutter

unread,
Feb 21, 2019, 10:37:23 AM2/21/19
to Eclipse MicroProfile
Phillip,
I know that with all of the forum postings, not everybody is reading or responding to them on a daily basis.  Given the four votes of confidence here, plus Andy's original suggestion on the Concurrency PR, I would say you could go ahead and redo the PRs.  I would maybe suggest doing the Concurrency PR first to get that team okay with the format and content.  And, then duplicate that across the other components to be consistent.  Sound like a plan?

-- Kevin

Phillip Krüger

unread,
Feb 21, 2019, 10:38:59 AM2/21/19
to Eclipse MicroProfile
Ok will do.
Thanks

Emily Jiang

unread,
Feb 21, 2019, 3:03:23 PM2/21/19
to Eclipse MicroProfile
First of all, thank you Phillip for taking prompt action to address the issue!

I have one concern. How can we make the meeting time more dynamic? As you see, some meetings (see Arthur's note on Open APIs meeting) will move around to fit better with the workgroup's availability. Very soon, the contribution.adoc is out of date.

Again, I think it is pretty much duplicating work to create the similar docs for each spec. Why don't we create a page on microprofile.io to announce how to contributor since we are trying to create a page (only need to link to the live calendar) on how to become a committer. How to contribute is pretty much a pre-req on how to become a committer?

Thoughts?

Emily

On Thursday, February 21, 2019 at 3:38:59 PM UTC, Phillip Krüger wrote:
Ok will do.
Thanks

Amelia Eiras

unread,
Feb 21, 2019, 4:11:02 PM2/21/19
to MicroProfile
Thats the plan Emily. 

To crete a doc that can assist the banner of that very page in MP website. 

Each page banner in the MP website must become effective, 1 click to enable action. 

Using the example of the Blog banner tab: “Become a MicroProfile Author”, this one will say: “become a microprofile Contributor” 

--
You received this message because you are subscribed to a topic in the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/-o0Mqv4I2IY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

Phillip Krüger

unread,
Feb 22, 2019, 12:33:32 AM2/22/19
to Eclipse MicroProfile
Hi Emily.

I think the adhoc meeting changes is more the exception than the rule. (I might be wrong). If the meeting times change permanently, the project team updates the contributing.adoc.

What I got from the community meeting is that "How to contribute" is not visible enough. (Hence the suggestion to add to the README).

The information is already available on the wiki (https://wiki.eclipse.org/MicroProfile) however it seems that is not enough.

I have made a change to now just have a link at the bottom of the README that links to the contributing page:

Screenshot_readme.png

This then link to the CONTRIBUTING page:

Screenshot_contributing.png



How about changing:

"Join our weekly meeting at ..."

to

"We usually meet weekly at ..., please join us (check the calendar to confirm the meeting)"

The other option is to just remove the CONTRIBUTING page and let the README just link to the wiki ?

Let me know what you think. 

On a slightly separate note: Should we not create a general README template, so that all projects have the same README structure ?

Kevin Sutter

unread,
Feb 22, 2019, 11:30:47 AM2/22/19
to Eclipse MicroProfile
Thanks, Phillip!  I like the new approach.  I was just looking at the Concurrency changes, and they look good.  Thanks!

I agree...  Standardizing the README format and content is another, bigger piece of work.  And, one that maybe doesn't need to be done.  Leaving that aspect up to the Component allows them to be more creative on what they want to promote about their Component.  Unless you are finding that certain critical information is missing from some of the READMEs?  Maybe that's the way to approach this...  Identifying items that need to be part of a README, but don't place rules on format or additional items that a Component might want to include.  Sounds like a separate thread would be good to discuss this aspect.

-- Kevin

Emily Jiang

unread,
Feb 22, 2019, 5:46:47 PM2/22/19
to Eclipse MicroProfile
Instead of duplicating the same distribution info in each individual spec, I think the info is better placed under "Contributors" of microprofile.io.

On clicking "Contributors", it should display what you have highlighted and then list all repos.

In this way, we have central cohesive recommendations in one place and point the contributors to an individual spec, which she/he is interested. Besides, microprofile.io is our landing page. Anyone who is new to MicroProfile will go to landing page first.

My 2cents.
Thanks
Emily

Amelia Eiras

unread,
Feb 22, 2019, 5:55:27 PM2/22/19
to MicroProfile
+1 Emily. 

each tab in MP website needs to be 1 click away on its banner to provide history, enough content to enable any visitor to actually act. 

This is a part of adding website features that are effective and practical to the point where the MicroProfile website becomes the source of truth for the project. 
Our goal is to make Microprofile adoption easier. Currently it is not. 

Adding value to project takes high amount of dedication, current hangout chats, issues created and this thread moves us by choice to decrease the amount of time currently required to participate. 

Super excited to see more issues added to the boards by everyone. 

--
You received this message because you are subscribed to a topic in the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/-o0Mqv4I2IY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

Emily Jiang

unread,
Feb 23, 2019, 5:44:58 PM2/23/19
to Eclipse MicroProfile
Yes, Amelia.

If you agree with me to add the contribution info on microprofile.io site, this will remove the need to duplicate the same info to individual specs, which to me it is overkill and it is very soon the info will out of sync.

many more

However, I do want to thank Phillip to spend time to do this.

Thoughts?

Emily

Amelia Eiras

unread,
Feb 25, 2019, 2:44:37 PM2/25/19
to MicroProfile, Phillip Kruger, Emily Jiang
Coffee at hand— Hola everyone :) 

Finally I think I understand there seems to be a confusion on current actions. 

There are 2 projects at work here being worked in parallel: 

  1. ASAP fix with adding the Tab to the Contributors, in process
  2. a larger project fix that requires the Project’s tab and the full page to be adjusted 180, not “really” started, yet issues are being created… and Phillip is adding major awesomeness to it.:)  

Phillip is working on both. 

The 1st one is easier b/c it uses the same WordPress feature as the Blog click guidelines bottom. 
The 2nd one is not. That means that for now, the individual projects will need their own source of truth b/c that source is required for them once the Project page is a priority. 

Project Website under the Marketing Repo is live since last week. 


Can either of you create a issue there and assign it to me once we have the very basic task (READMe- first step)?

Happy Monday MicroProfilers, 

Emily Jiang

unread,
Feb 25, 2019, 5:59:08 PM2/25/19
to Eclipse MicroProfile
Amelia,

ASAP fix with adding the Tab to the Contributors, in process
My previous emails suggest this option. I would like all PRs created by Phillip on individual specs to be closed if we add the instruction at the landing page.

  1. a larger project fix that requires the Project’s tab and the full page to be adjusted 180, not “really” started, yet issues are being created… and Phillip is adding major awesomeness to it.:)  
What do you mean about this one?

Thanks
Emily

Kevin Sutter

unread,
Feb 26, 2019, 10:25:38 AM2/26/19
to Eclipse MicroProfile
Emily and Amelia,
I do not agree with just having the central location for "how to contribute"...  We can definitely create a central location for this information, but this shouldn't be the only location.  Each component should also have their "how to contribute" file that Philip is creating.  We will have people that are only interested in Fault Tolerance, for example.  They should see "how to contribute" just be visiting the github repo.  They shouldn't have to hunt around attempting to find this central location.  And, even if each component has a link to this central location, the information is now unwieldy...  Every component's unique information for their hangout, minutes, gitter info, etc will need to be on this central location.

I actually think it would be better to continue down the path that Philip has started with individual Component CONTRIBUTION.adoc files.  Then, in the central location, we can have a general "how to contribute" with links to each of the component's unique CONTRIBUTION.adoc files.

-- Kevin

Ken Finnigan

unread,
Feb 26, 2019, 10:28:35 AM2/26/19
to MicroProfile
To prevent unnecessary duplication, maybe each component has a contributing doc that essentially points to a central doc for information about common aspects, but then it has its specific gitter room, etc in its own doc?

You received this message because you are subscribed to the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/93f1875d-40cb-4f38-8e50-512f770e10d9%40googlegroups.com.

Emily Jiang

unread,
Feb 26, 2019, 12:44:59 PM2/26/19
to Eclipse MicroProfile

Hi Kevin,

They shouldn't have to hunt around attempting to find this central location.  And, even if each component has a link to this central location, the information is now unwieldy...  Every component's unique information for their hangout, minutes, gitter info, etc will need to be on this central location.

They won't need to hunt around. The landing page is microprofile.io. All entry info should be there. On how to contributing, it should list the info and then have the choice to go to each spec. e.g. if they go to each spec, they can directly join the gitter, where live conversation can happen there. I dislike the fact each repo having the dup info on how to contribute and maintain whenever you change your meetings etc. Changing meetings can happen from time to time. MP calendar and gitter has more accurate info.




I actually think it would be better to continue down the path that Philip has started with individual Component CONTRIBUTION.adoc files.  Then, in the central location, we can have a general "how to contribute" with links to each of the component's unique CONTRIBUTION.adoc files.

I prefer to add info to readme or even gitter as we have done for FT (https://gitter.im/eclipse/microprofile-fault-tolerance). On the top of gitter, it has meeting time and minutes doc. We also remind people for meetings. Basically, give flexibility to spec to engage with developers.

Thanks
Emily

Emily Jiang

unread,
Feb 26, 2019, 12:45:46 PM2/26/19
to Eclipse MicroProfile

Ken,
This is better. Actually, we can add the link to readme which is more visible.
Emily

Alasdair Nottingham

unread,
Feb 26, 2019, 1:08:49 PM2/26/19
to microp...@googlegroups.com
If I go to the GitHub repo for a spec I’d expect to find out how to contribute without having to go to MicroProfile.io

Alasdair Nottingham
You received this message because you are subscribed to the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

Ladislav Thon

unread,
Feb 26, 2019, 1:21:04 PM2/26/19
to MicroProfile
út 26. 2. 2019 v 19:08 odesílatel Alasdair Nottingham <alasdair....@gmail.com> napsal:
If I go to the GitHub repo for a spec I’d expect to find out how to contribute without having to go to MicroProfile.io

+1. I never go to microprofile.io, I always go directly to GitHub.

LT
 

Amelia Eiras

unread,
Feb 26, 2019, 2:46:15 PM2/26/19
to MicroProfile
I created an issue after the hangout last week :)

Fix Contributors bottom "want To Become A Contributor" link


Please add the basic link for the adjustment of that tab. Agreed that each repo project needs to stand on its own as that is the very value of MP, to allow independence. 

The second task to re-work the Projects page in the site is a work in process. each repo needs to be it— beefing it to own: “it is that easy to contribute” suffices if there is a simple how to start.

I like this thread, yet we must watch how “picky”do we choose to be with adjustments. Anything we do must add value to integrate that 1 new contributor or user.

 Let's cut debt, less is more!   

Emily Jiang

unread,
Feb 26, 2019, 5:20:13 PM2/26/19
to Eclipse MicroProfile
It is fine. I mentioned earlier. In github, readme, a link will be added to point to the how to page (see my response to Ken). The readme is a better place to display info not the contribution.adoc though.
Emily

Emily Jiang

unread,
Feb 27, 2019, 8:58:30 AM2/27/19
to Eclipse MicroProfile
Let me summarise the discussion so that people join in late can have the full picture:

Current approach:

Duplicate the same contributor.adoc in every single mp project. See the following PRs

....
Recommended approach:

1. put contributor.adoc info to microprofile.io/ under contribute tag add "how to contribute" maybe.

2. In readme of each project, it can link to the webpage of how to contribute.

Ken and I discussed this in our service mesh hangout earlier and feel this reduce the duplication and maintain just one page instead of many of them.

For someone who is new to MP, they will normally visit microprofile.io. They can immediately find the how to they need. For someone who is familiar to MP like Alasdair or LT, you can visit to the individual spec and still can find how to contribute via readme, which is the landing page for the specs.

Basically, I just try to remove the duplication and out-of-sync headaches.

Please share your opinion here.
Thanks
Emily
For more options, visit <a href="https://groups.google.com/d/optout" style="font-family:Verdana;font-size:12px;font-style:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" rel="nofollow" target="_blank" onmousedown="this.href='https://groups.google.com/d/optout';return true;" onclick="this.href='https://group

Phillip Krüger

unread,
Feb 27, 2019, 11:22:01 AM2/27/19
to Eclipse MicroProfile
Hi Emily and others.

The contribute.adoc is not the same in every project. It has the same structure and contains links to some of the same places for more information, but the important parts are different.

contribute.png

Let's look at each element ordered by the likely-hood of change (and creating an out of sync problem as you fear):

1) Most likely to change is the time, date and frequency of the project meeting. This is owned by the project team and they should be able to change this easy. The contribute.adoc contains this info with a link to the MP Calendar. This does not make sense to maintain central on microprofile.io, as it's different per project.

2) Second likely is the URL to the meeting room (Bluejeans, Zoom, Webex). Again, same argument as above.

From now on the changes of data changing is very low, and does not warrant being used in this argument:

3) The URL to the google doc containing the Agenda and meeting minutes. Still different per project but should not change.

4) The URL to the gitter room. Different per project but should not change.

5) The URL to the issues, Different per project but should not change.

6) All the rest is deep links to places with more info (MP Wiki and GitHub help) and this has a low chance of changing.

So. The only data that really can go out of sync, is anyway different per project and owned by the project team, so they should be able to change this. I am not sure how / what tech the microprofile.io web is build on, and if projects teams can change parts of it, but I would imagine it will be harder than an adoc in your own project.

Finally, I would suggest that we only address your concerns if they happen. If we see that maintaining these contribute.adoc files is a nightmare and we are constantly out of sync, then find a solution for that. I doubt that it will happen, but, I might be wrong.

Cheers

Emily Jiang

unread,
Feb 27, 2019, 11:30:42 AM2/27/19
to Eclipse MicroProfile
For the project specific info, they are in calendar invitation, which is more up to date. I normally put the link to the gitter as well. Maybe in readme, a link should also be created to point to calendar.

Emily
You received this message because you are subscribed to a topic in the Google Groups "Eclipse MicroProfile" group.<br style="font-family:Verdana;font-size:12px;font-style:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decor

Phillip Krüger

unread,
Feb 27, 2019, 12:13:30 PM2/27/19
to Eclipse MicroProfile
Hi Emily,

So are you saying adding a link like this to README is enough ?


I don't disagree, all the information is there, not sure if a potential new contributor will find that enough, but I am happy to assist changing accordingly.

Cheers
</bl

Emily Jiang

unread,
Feb 28, 2019, 8:07:15 AM2/28/19
to Eclipse MicroProfile
Hi Phillip,

Pretty much. Adding links to calendar and to the central contribution page is enough, in my view.

Thanks for being patient!

Emily

Kevin Sutter

unread,
Feb 28, 2019, 8:58:55 AM2/28/19
to Eclipse MicroProfile
Phillip,
That type of calendar link is good if we're using it for a specific hangout.  But, I still think we should have a general link to the whole calendar.  Maybe that's part of your "static" content?

This discussion is going in so many different directions, I can't keep it all straight.  I still think we need some type of README/CONTRIBUTION update in each github repo.  Several people have indicated on this thread that github is where they will go to find out about a project.  They may eventually get to microprofile.io, but that won't be the first place that a developer will look.  So, I'm fine if microprofile.io is the holding area for some of the static information.  But, project-specific information and information that might change needs to be easy to maintain and easy to find.  And, that points back to the github repo.  I'm sorry to say this, but microprofile.io has been painful to update.  And, I don't think everyone in the MP development community needs to know how to update microprofile.io.

-- Kevin

Amelia Eiras

unread,
Mar 18, 2019, 4:09:50 PM3/18/19
to Eclipse MicroProfile
Where are we on this?

Do we need to re-add it to agenda?

On Wednesday, February 20, 2019 at 8:25:05 AM UTC-8, Kevin Sutter wrote:
Hi,
Per our discussion on the Google Hangout yesterday, Phillip went ahead and created PRs for many of our component repos to indicate how to get involved and how to contribute...  I greatly appreciate the work that was put in, but I'm not convinced that the README is the best place for this information.  The README should provide a quick, easy overview of the component and how to get started with it.  Leading off with the Contributing Guidelines looks to be a bit much.

As Andy has pointed out in one of the PRs, maybe a better place would be a CONTRIBUTING.md file...  We are supposed to have those in our component repos, but Eclipse doesn't enforce the rule.  If we could create or update the CONTRIBUTING.md file for each affected repo and then maybe just provide a pointer to that file from the README somewhere, maybe that would allow us to still document the processes without cluttering up the README?

Thoughts?
Kevin

Phillip Krüger

unread,
Apr 30, 2019, 11:42:27 AM4/30/19
to Eclipse MicroProfile
Hi All.


Let me know if this is what you had in mind.

Cheers.
Phillip

Amelia Eiras

unread,
Apr 30, 2019, 12:55:53 PM4/30/19
to MicroProfile, Phillip Kruger
time 10x better to what it is today, comments in the issue :) thank you for sending update to forum, you Rock! 
-- 
You received this message because you are subscribed to a topic in the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/-o0Mqv4I2IY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to microprofile...@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.
Reply all
Reply to author
Forward
0 new messages