You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by Eugen Stan <eu...@netdava.com> on 2020/07/20 11:00:13 UTC
Which repositories are we using and going to document? Let's retire
the ones we don't
Hello,
While working on the documentation website I ran into the question of:
What parts to document?
1. What are the repositories we still use in James - some like jdkim
have merged in james-project - others ?
2. Which ones we don't use?
3. Which projects we wish to retire - if any? My suggestion: hupa, but
we need to make a call and see if anyone steps in?
Current list of repositories: https://gitbox.apache.org/repos/asf#james
james-hupa.git <https://gitbox.apache.org/repos/asf/james-hupa.git>
Apache James Hupa 23 weeks ago
james-jdkim.git <https://gitbox.apache.org/repos/asf/james-jdkim.git>
Apache James jdkim 42 weeks ago
james-jsieve.git <https://gitbox.apache.org/repos/asf/james-jsieve.git>
Apache James jsieve 42 weeks ago
james-jspf.git <https://gitbox.apache.org/repos/asf/james-jspf.git>
Apache James jspf 42 weeks ago
james-mime4j.git <https://gitbox.apache.org/repos/asf/james-mime4j.git>
Apache James mime4j 3 days ago
james-postage.git
<https://gitbox.apache.org/repos/asf/james-postage.git> Apache James
postage 75 weeks ago
james-project.git
<https://gitbox.apache.org/repos/asf/james-project.git> Apache James
project 3 days ago
james-site.git <https://gitbox.apache.org/repos/asf/james-site.git>
Apache James Website <30 minutes ago
== More context
Antora has a nice system - called [component-version] - that allows us
to keep the documentation next to the sources and have multiple version
of it.
Right now we have this setup with only James project -
https://github.com/apache/james-site/blob/live/doc-sites/antora-playbook.yml
I do believe we should keep the documentation in every project and
publish them as components.
We can add edit links back to github for each page.
I'll create a component-version for each project and try to migrate as
much documentation as I can (help needed).
The website should be published from james-site which IMO should also
contain the Jekyll content.
[component-version] https://docs.antora.org/antora/2.3/component-version/
--
Eugen Stan
+40720 898 747 / netdava.com
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Rene Cordier <rc...@apache.org>.
On 20/08/2020 11:23, Rene Cordier wrote:
>
> Based on Eugen comments in the INFRA ticket, I did this:
> https://github.com/apache/james-project/pull/244 for redirecting
> notifications to the new ML for this.
>
> However I don't think as a commiter I can create the ML, so if a PMC
> could manage that :)
Following the fact that the ML has been created, I merged the pull
request. I could subscribe to it and I saw Eugen sending a test mail
through successfully as well.
But every time something get merged for example, I get an error email
from INFRA saying:
"An error occurred while running notifications feature in .asf.yaml!:
Invalid notification target 'notifications@james.apache.org'. Must be a
valid @james.apache.org list!"
However the ML exists and looks valid. Thus I do not understand what is
going on... I did reported the issue on INFRA ticket, but still waiting
for an answer.
If anybody got an idea, you are welcome to speak. If not well... I guess
we need to wait for INFRA to answer us.
Cheers,
Rene.
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Rene Cordier <rc...@apache.org>.
On 19/08/2020 17:49, Eugen Stan wrote:
> I've created an issue to make the ML changes:
> https://issues.apache.org/jira/browse/INFRA-20735
>
> --
> Please add:
> - notifications@james.apache.org
> Please remove:
> - site-dev@james.apache.org
> - mailet-api@james.apache.org
Based on Eugen comments in the INFRA ticket, I did this:
https://github.com/apache/james-project/pull/244 for redirecting
notifications to the new ML for this.
However I don't think as a commiter I can create the ML, so if a PMC
could manage that :)
Rene.
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Eugen Stan <eu...@netdava.com>.
La 19.08.2020 09:59, Rene Cordier a scris:
>> I think we should have separate channels for:
>> - development: how we implement features and what features we work on
>> - users: how to use James:deploy it, create back-ups, etc.
>
> Those 2 mailing lists exist already I believe. We have `server-dev` for
> development related things and `server-user` for users concerns.
>
> I agree though with potentially making an other ML to separate the
> notifications from development concerns posted by members, as all of
> that is sent through the server-dev ML for now.
I've created an issue to make the ML changes:
https://issues.apache.org/jira/browse/INFRA-20735
--
Please add:
- notifications@james.apache.org
Please remove:
- site-dev@james.apache.org
- mailet-api@james.apache.org
--
>> Gitter should be added if that is a channel.
>> I do think we should have 2 channels for dev and user on gitter.
>
> Gitter I think is more for giving help and support to users and
> answering problems. I don't think we need two Gitter channels for this,
> the one we have currently is enough?
Sometimes it is easier to have a quick discussion for development on
chat and then put the conclusions on ML / JIRA / PR.
Those discussions would be better off on a different channel then the
one used to talk with users.
--
Eugen Stan
+40720 898 747 / netdava.com
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Rene Cordier <rc...@apache.org>.
> I think we should have separate channels for:
> - development: how we implement features and what features we work on
> - users: how to use James:deploy it, create back-ups, etc.
Those 2 mailing lists exist already I believe. We have `server-dev` for
development related things and `server-user` for users concerns.
I agree though with potentially making an other ML to separate the
notifications from development concerns posted by members, as all of
that is sent through the server-dev ML for now.
> Gitter should be added if that is a channel.
> I do think we should have 2 channels for dev and user on gitter.
Gitter I think is more for giving help and support to users and
answering problems. I don't think we need two Gitter channels for this,
the one we have currently is enough?
Rene.
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Eugen Stan <eu...@netdava.com>.
La 17.08.2020 07:45, David Leangen a scris:
>
>> I do think we might want to leverage this opportunity to close
>> low-traffic unused mailing lists. This includes:
>
>
>
> My 2 cents:
>
> From the user perspective, I think it would be desirable to trim down the number of mailing lists. 😀
>
Thank you for taking care of this.
I'm busy with company work.
I agree with trimming down the mailing list.
Automatic notifications is another issue.
We have:
- git notifications - commit, merge, pr, etc
- jira notifications - comment, create, etc
Right now we send them to the development ML which is a good solution IMO.
Users can filter them out n the client.
Another option is to create separate ML for notifications.
I think we should have separate channels for:
- development: how we implement features and what features we work on
- users: how to use James:deploy it, create back-ups, etc.
Gitter should be added if that is a channel.
I do think we should have 2 channels for dev and user on gitter.
--
Eugen Stan
+40720 898 747 / netdava.com
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by David Leangen <ap...@leangen.net>.
> I do think we might want to leverage this opportunity to close
> low-traffic unused mailing lists. This includes:
My 2 cents:
From the user perspective, I think it would be desirable to trim down the number of mailing lists. 😀
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Tellier Benoit <bt...@apache.org>.
Hi René
I did a quick review.
As such, given the limited content, I mostly agree with it.
I do think we might want to leverage this opportunity to close
low-traffic unused mailing lists. This includes:
 -site-dev@james.apache.org : site discussions happens on server-dev and
not there, it is low traffic, and unused.
 - mailet-api@james.apache.org: It is not active.... Maybe it is better
to discuss mailet api concerns in server-dev....
What would the list think about such an initiative?
Best regards,
Benoit
Le 17/08/2020 à 10:26, Rene Cordier a écrit :
> Hello,
>
>> There are things that need to me documented that are not technical:
>> - what / where are the project resources (website, CI, git repos,
>> mailing list)
>> - how to contribute, engage with the community
>> - etc.
>
> Just to say I started migrating and writing this part of the
> documentation here: https://github.com/apache/james-project/pull/243
>
> Don't hesitate to put comments and give feedbacks.
>
> Thanks!
>
> Rene.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
> For additional commands, e-mail: server-dev-help@james.apache.org
>
>
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Rene Cordier <rc...@apache.org>.
Hello,
> There are things that need to me documented that are not technical:
> - what / where are the project resources (website, CI, git repos,
> mailing list)
> - how to contribute, engage with the community
> - etc.
Just to say I started migrating and writing this part of the
documentation here: https://github.com/apache/james-project/pull/243
Don't hesitate to put comments and give feedbacks.
Thanks!
Rene.
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by David Leangen <ap...@leangen.net>.
> Migrating is not sexy work but is easier than writing new documentation.
Conditional on the structure and content being in a desirable state, I would agree with this generalization. In this case, though, I don’t feel the condition is me, so I think we’ll have to agree to disagree.
> I've added edit-url capabilites, changed the homepage to be in james-site and renamed main to james-project .https://james.staged.apache.org/jdkim/0.3-SNAPSHOT/index.html .
Thanks!
> I'm curios how the structure is going to evolve.
Me, too!
Cheers,
=David
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Eugen Stan <eu...@netdava.com>.
La 31.07.2020 03:13, David Leangen a scris:
>> I've decided to add docs stubs to all repositories.
>> I'm going to start migrating the documentation for the popular libraries and then decide what to do with the others (start the retiring process most likely).
>
> Awesome! Nice initiative. Thanks!!
>
>
>> Anyone up for a documentation migration party?
>
> As I mentioned before, I am quite skeptical of just migrating documents. I won’t stop you, but I’m not sure it would add value, because I think the sites need to be rewritten from scratch. So taking the sources from where they are now would be just fine IMO.
Migrating is not sexy work but is easier than writing new documentation.
It's also faster and it gives us a chance to know what we have and check
the documentation.
There are things that need to me documented that are not technical:
- what / where are the project resources (website, CI, git repos,
mailing list)
- how to contribute, engage with the community
- etc.
I've added edit-url capabilites, changed the homepage to be in
james-site and renamed main to james-project
.https://james.staged.apache.org/jdkim/0.3-SNAPSHOT/index.html .
By the way David, you can edit the documentation homepage
https://james.staged.apache.org/ to add description about the modules.
My next goals are
- add text to encourage people to contribute to the docs (edit pages)
- figure out what to do with the top menu (Home, products, Services,
etc). =>>> Help needed
- test-migrate a small library (jdkim / jspf ?!)
I'm curios how the structure is going to evolve.
--
Eugen Stan
+40720 898 747 / netdava.com
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by David Leangen <ap...@leangen.net>.
> I've decided to add docs stubs to all repositories.
> I'm going to start migrating the documentation for the popular libraries and then decide what to do with the others (start the retiring process most likely).
Awesome! Nice initiative. Thanks!!
> Anyone up for a documentation migration party?
As I mentioned before, I am quite skeptical of just migrating documents. I won’t stop you, but I’m not sure it would add value, because I think the sites need to be rewritten from scratch. So taking the sources from where they are now would be just fine IMO.
Cheers,
=David
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Eugen Stan <eu...@netdava.com>.
La 21.07.2020 01:23, David Leangen a scris:
>
>>> While working on the documentation website
>
> I have been distracted by other work the past 2 weeks. I hope to get back to this project within this week.
>
> Thanks for helping to push it forward!
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
> For additional commands, e-mail: server-dev-help@james.apache.org
>
I've decided to add docs stubs to all repositories.
I'm going to start migrating the documentation for the popular libraries
and then decide what to do with the others (start the retiring process
most likely).
https://issues.apache.org/jira/browse/JAMES-3226
https://james.staged.apache.org/james-site/latest/index.html
Anyone up for a documentation migration party?
--
Eugen Stan
+40720 898 747 / netdava.com
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by David Leangen <ap...@leangen.net>.
>> While working on the documentation website
I have been distracted by other work the past 2 weeks. I hope to get back to this project within this week.
Thanks for helping to push it forward!
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Which repositories are we using and going to document? Let's
retire the ones we don't
Posted by Tellier Benoit <bt...@apache.org>.
Le 20/07/2020 à 18:00, Eugen Stan a écrit :
> Hello,
>
> While working on the documentation website I ran into the question of:
> What parts to document?
>
> 1. What are the repositories we still use in James - some like jdkim
> have merged in james-project - others ?
No.
The JDKIM library still lives indepandantly from James.
Only it's mailet integration with the james server had been merged into
james-project.
The usage of JDKIM as a library would still benefit from being documented.
>
> 2. Which ones we don't use?
>
> 3. Which projects we wish to retire - if any? My suggestion: hupa, but
> we need to make a call and see if anyone steps in?
>
>
> Current list of repositories: https://gitbox.apache.org/repos/asf#james
>
> james-hupa.git <https://gitbox.apache.org/repos/asf/james-hupa.git>
> Apache James Hupa    23 weeks ago
+1 for retirement.
> james-jdkim.git <https://gitbox.apache.org/repos/asf/james-jdkim.git>
> Apache James jdkim    42 weeks ago
This one is used as explained above/
> james-jsieve.git
> <https://gitbox.apache.org/repos/asf/james-jsieve.git> Apache James
> jsieve    42 weeks ago
Used too. Even as
https://www.mail-archive.com/server-dev@james.apache.org/msg65858.html
pointed out we might benefit from a nicer API...
> james-jspf.git <https://gitbox.apache.org/repos/asf/james-jspf.git>
> Apache James jspf    42 weeks ago
Used too.
> james-mime4j.git
> <https://gitbox.apache.org/repos/asf/james-mime4j.git> Apache James
> mime4j    3 days ago
Used.
> james-postage.git
> <https://gitbox.apache.org/repos/asf/james-postage.git>Â Â Â Â Apache
> James postage    75 weeks ago
I must confess I never used postage for load testing. I'm a stranger to
this sub-part of the project.
Some alternaves exist as JMeter extensions or Gatling libraries (IMAP,
JMAP & SMTP)
Maybe, given that their is very little contributions on this project we
could consider retiring it?
> james-project.git
> <https://gitbox.apache.org/repos/asf/james-project.git>Â Â Â Â Apache
> James project    3 days ago
> james-site.git <https://gitbox.apache.org/repos/asf/james-site.git>
> Apache James Website    <30 minutes ago
>
>
> == More context
>
> Antora has a nice system - called [component-version] - that allows us
> to keep the documentation next to the sources and have multiple
> version of it.
>
> Right now we have this setup with only James project -
> https://github.com/apache/james-site/blob/live/doc-sites/antora-playbook.yml
>
>
> I do believe we should keep the documentation in every project and
> publish them as components.
+1
>
> We can add edit links back to github for each page.
>
> I'll create a component-version for each project and try to migrate as
> much documentation as I can (help needed).
I've started migrating documentation for the Distributed Server and am
making good progress on it.
I'm expecting the Advanced server to go faster.
I'm also interested into migrating the community part of the james site
to Antora.
>
> The website should be published from james-site which IMO should also
> contain the Jekyll content.
+1 this would be more natural.
>
>
> [component-version] https://docs.antora.org/antora/2.3/component-version/
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
> For additional commands, e-mail: server-dev-help@james.apache.org