README
author Philippe Pepiot <philippe.pepiot@logilab.fr>
Tue, 15 Oct 2019 15:30:56 +0200
changeset 12734 d177d8ab4fd3
parent 12570 82bf85157b53
permissions -rw-r--r--
Document mercurial configuration for contributing * how to use master/review repositories * how to send the "Available at" command in patchbomb emails * how to add the "cubicweb" flag in patchbomb emails * how to use our "jenkins" mercurial extension Closes #17243538
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2562
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
     1
CubicWeb semantic web framework
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
     2
===============================
2562
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
     3
5024
9e718abe3fde add egg support with dependencies auto-installation
Alain Leufroy <alain.leufroy@logilab.fr>
parents: 2562
diff changeset
     4
CubicWeb is a entities / relations based knowledge management system
9e718abe3fde add egg support with dependencies auto-installation
Alain Leufroy <alain.leufroy@logilab.fr>
parents: 2562
diff changeset
     5
developped at Logilab.
9e718abe3fde add egg support with dependencies auto-installation
Alain Leufroy <alain.leufroy@logilab.fr>
parents: 2562
diff changeset
     6
9e718abe3fde add egg support with dependencies auto-installation
Alain Leufroy <alain.leufroy@logilab.fr>
parents: 2562
diff changeset
     7
This package contains:
7741
45251e611209 [doc] fix ReST in README file (make pypi happier)
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7613
diff changeset
     8
45251e611209 [doc] fix ReST in README file (make pypi happier)
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7613
diff changeset
     9
- a repository server
45251e611209 [doc] fix ReST in README file (make pypi happier)
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7613
diff changeset
    10
- a RQL command line client to the repository
45251e611209 [doc] fix ReST in README file (make pypi happier)
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7613
diff changeset
    11
- an adaptative modpython interface to the server
45251e611209 [doc] fix ReST in README file (make pypi happier)
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7613
diff changeset
    12
- a bunch of other management tools
5024
9e718abe3fde add egg support with dependencies auto-installation
Alain Leufroy <alain.leufroy@logilab.fr>
parents: 2562
diff changeset
    13
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    14
Install
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    15
-------
2562
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    16
12262
282bc6fb50fd Link to "3.26" docs in README
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12141
diff changeset
    17
More details at https://cubicweb.readthedocs.io/en/3.26/book/admin/setup
2562
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    18
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    19
Getting started
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    20
---------------
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    21
7741
45251e611209 [doc] fix ReST in README file (make pypi happier)
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7613
diff changeset
    22
Execute::
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    23
12532
38004d09d178 [doc] Update README "Getting started"
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12375
diff changeset
    24
 python3 -m venv venv
38004d09d178 [doc] Update README "Getting started"
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12375
diff changeset
    25
 source venv/bin/activate
38004d09d178 [doc] Update README "Getting started"
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12375
diff changeset
    26
 pip install 'cubicweb[pyramid]' cubicweb-blog
2562
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    27
 cubicweb-ctl create blog myblog
12532
38004d09d178 [doc] Update README "Getting started"
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12375
diff changeset
    28
 # read how to create your ~/etc/cubicweb.d/myblog/pyramid.ini file here:
38004d09d178 [doc] Update README "Getting started"
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12375
diff changeset
    29
 # https://cubicweb.readthedocs.io/en/latest/book/pyramid/settings/#pyramid-settings-file
38004d09d178 [doc] Update README "Getting started"
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12375
diff changeset
    30
 # then start your instance:
38004d09d178 [doc] Update README "Getting started"
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12375
diff changeset
    31
 cubicweb-ctl pyramid -D myblog
2562
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    32
 sensible-browser http://localhost:8080/
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    33
12262
282bc6fb50fd Link to "3.26" docs in README
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12141
diff changeset
    34
Details at https://cubicweb.readthedocs.io/en/3.26/tutorials/base/blog-in-five-minutes
2562
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    35
12372
392aa430bf96 [README] point to logilab's jenkins in tests section
Laurent Peuch <cortex@worlddomination.be>
parents: 12262
diff changeset
    36
You can also look at the latest builds on Logilab's jenkins:
392aa430bf96 [README] point to logilab's jenkins in tests section
Laurent Peuch <cortex@worlddomination.be>
parents: 12262
diff changeset
    37
https://jenkins.logilab.org/
392aa430bf96 [README] point to logilab's jenkins in tests section
Laurent Peuch <cortex@worlddomination.be>
parents: 12262
diff changeset
    38
12570
82bf85157b53 [README] add testing instructions
Laurent Peuch <cortex@worlddomination.be>
parents: 12532
diff changeset
    39
Test
82bf85157b53 [README] add testing instructions
Laurent Peuch <cortex@worlddomination.be>
parents: 12532
diff changeset
    40
----
82bf85157b53 [README] add testing instructions
Laurent Peuch <cortex@worlddomination.be>
parents: 12532
diff changeset
    41
82bf85157b53 [README] add testing instructions
Laurent Peuch <cortex@worlddomination.be>
parents: 12532
diff changeset
    42
Simply run the `tox` command in the root folder of this repository:
82bf85157b53 [README] add testing instructions
Laurent Peuch <cortex@worlddomination.be>
parents: 12532
diff changeset
    43
82bf85157b53 [README] add testing instructions
Laurent Peuch <cortex@worlddomination.be>
parents: 12532
diff changeset
    44
    tox
82bf85157b53 [README] add testing instructions
Laurent Peuch <cortex@worlddomination.be>
parents: 12532
diff changeset
    45
82bf85157b53 [README] add testing instructions
Laurent Peuch <cortex@worlddomination.be>
parents: 12532
diff changeset
    46
How to install tox: https://tox.readthedocs.io/en/latest/install.html
82bf85157b53 [README] add testing instructions
Laurent Peuch <cortex@worlddomination.be>
parents: 12532
diff changeset
    47
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    48
Documentation
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    49
-------------
2562
dd76d0f88796 [doc] #120075 quickstart (was proposed structure)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    50
12262
282bc6fb50fd Link to "3.26" docs in README
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12141
diff changeset
    51
Look in the doc/ subdirectory or read https://cubicweb.readthedocs.io/en/3.26/
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    52
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    53
12106
eeb2b2ec1928 Make entypo link a true URL in README
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12105
diff changeset
    54
CubicWeb includes the Entypo pictograms by Daniel Bruce — http://www.entypo.com
12141
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    55
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    56
Contributing
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    57
------------
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    58
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    59
Patches should be submitted by email at the cubicweb-devel@lists.cubicweb.org
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    60
mailing list in order to get reviewed by project integrators or any community
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    61
member.
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    62
The simplest way of send patches is to use the ``hg email`` command available
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    63
through the *patchbomb* extension of Mercurial. Preferably, patches should be
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    64
*in the message body* of emails. When submitting a revised version of a patch
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    65
series, a prefix indicating the iteration number ``<n>`` of the series should
29d032bb70d8 Add a "Contributing" section to README with patch submission guidelines
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 12106
diff changeset
    66
be added to email subject prefixes; this can be achieved by specifying a
12373
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    67
``--flag v<n>`` option to ``hg email`` command. If needed you can also use the
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    68
--in-reply-to option.
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    69
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    70
Examples:
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    71
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    72
    hg email --to cubicweb-devel@lists.cubicweb.org --intro -r <start>::<end>
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    73
    hg email --flag V2 --to cubicweb-devel@lists.cubicweb.org -r <start>::<end>
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    74
12375
e7221f2123e6 [README] point to xmpp room for contributors
Laurent Peuch <cortex@worlddomination.be>
parents: 12373
diff changeset
    75
If you have any questions you can also come on Logilab's public XMPP room using
e7221f2123e6 [README] point to xmpp room for contributors
Laurent Peuch <cortex@worlddomination.be>
parents: 12373
diff changeset
    76
a XMPP client: public@conference.jabber.logilab.org
e7221f2123e6 [README] point to xmpp room for contributors
Laurent Peuch <cortex@worlddomination.be>
parents: 12373
diff changeset
    77
12373
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    78
Mailing list: https://lists.cubicweb.org/mailman/listinfo/cubicweb-devel
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    79
Patchbomb extension: https://www.mercurial-scm.org/wiki/PatchbombExtension
e7ef70b3a0eb [README] improve contribution section with links and command examples
Laurent Peuch <cortex@worlddomination.be>
parents: 12372
diff changeset
    80
Good practice on sending email patches: https://www.mercurial-scm.org/wiki/ContributingChanges#Emailing_patches
12734
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    81
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    82
Full .hg/hgrc example for contributors having ssh access to ``hg.logilab.org`` :
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    83
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    84
    [paths]
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    85
    default = https://hg.logilab.org/master/cubicweb
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    86
    default-push = ssh://hg@hg.logilab.org/review/cubicweb
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    87
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    88
    [email]
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    89
    to = cubicweb-devel@lists.cubicweb.org
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    90
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    91
    [patchbomb]
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    92
    publicurl = https://hg.logilab.org/review/cubicweb
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    93
    flagtemplate = "{separate(' ', 'cubicweb', flags)}"
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    94
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    95
    [jenkins]
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    96
    url = https://jenkins.logilab.org/
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    97
    job = cubicweb-default
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    98
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
    99
If you don't have ssh access to ``hg.logilab.org``, you can use your own Mercurial server and
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   100
change ``default-push`` and ``publicurl`` accordingly.
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   101
A list of services that provides hosting of Mercurial repositories is available
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   102
on https://www.mercurial-scm.org/wiki/MercurialHosting.
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   103
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   104
* ``hg pull`` will pull on master repo (public changesets).
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   105
* ``hg push`` will push on review repo using ssh.
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   106
* When sending an email to the list, it will add a "Available at" with command
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   107
  to pull the draft series on the public repo.
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   108
* Using https://hg.logilab.org/master/logilab/devtools/file/tip/hgext/jenkins.py
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   109
  mercurial extension, ``hg show jenkins`` display jenkins build status for
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   110
  each changeset. Read https://www.mercurial-scm.org/wiki/UsingExtensions to learn how
d177d8ab4fd3 Document mercurial configuration for contributing
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12570
diff changeset
   111
  to enable a new extension in mercurial.