Skip to content

Commit 3e98296

Browse files
jeff5jeff5
authored
Begin a developer guide in the repo (jython#420)
We add some process documentation in Markdown, beginning with the release process converted from reStructuredText, the coding standard (from wiki), and a few words on the CLA. We have Git ignore virtual environments *.venv so that we can run the spell-checking locally.
1 parent 4977f8d commit 3e98296

5 files changed

Lines changed: 1062 additions & 0 deletions

File tree

‎ProcessDocs/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Jython Project Processes
2+
3+
This is an incomplete guide for Jython developers and contributors,
4+
to processes we apply during development.
5+
6+
We aspire to processes and principles from
7+
the [Python Developer Guide](https://devguide.python.org/)
8+
where they are generic enough to apply to us.
9+
That guide, in its processes and cheat-sheets,
10+
is oriented strongly towards the C implementation of Python.
11+
Here we aim to provide versions of those things specific to Jython,
12+
our repositories, and a Java implementation[^1].
13+
14+
It will not, to begin with,
15+
contain sections for everything that could be translated to Java.
16+
Where it falls short,
17+
readers should make an intelligent interpretation of the (C)Python Dev Guide
18+
for a Java context,
19+
and consider contributing that here.
20+
21+
22+
## Contents
23+
24+
1. Setup and building (adapt from CPython and Jython Wiki)
25+
1. Git bootcamp (adapt from CPython)
26+
1. [Contributor agreement](contributor_agreement.md)
27+
1. [Coding standard](coding_standard.md)
28+
1. Lifecycle of a change (adapt from CPython)
29+
1. [Releasing a version](releasing.md)
30+
31+
32+
[^1]: We have several times tried to maintain a complete Jython Developer Guide
33+
based on the [Python Developer Guide](https://devguide.python.org/),
34+
and incorporating material from it.
35+
Keeping common material in sync proved too difficult.

‎ProcessDocs/coding_standard.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Coding Standard
2+
3+
When contributing code or patches to Jython,
4+
please try to follow these guidelines.
5+
6+
This guidance is quite old (Java 6 or earlier)
7+
so will not answer all questions.
8+
It applies to Jython 2.
9+
It has been rescued from the Jython Wiki.
10+
11+
Parts of the Jython code base do not conform very well to this guide.
12+
(They may be even older than the rules.)
13+
Avoid the temptation to reformat them when working on a contribution,
14+
as it makes it difficult for a reviewer to see
15+
the code change being contributed.
16+
17+
18+
## Python Code
19+
20+
In general, follow PEP 8.
21+
22+
When importing Java code, always use fully qualified class names,
23+
not package names i.e. `from java.lang import String`
24+
instead of `from java import lang`.
25+
26+
## Java Code
27+
28+
In general, have in mind that code is read more times than it is written,
29+
and that contributors not familiar with your thinking
30+
will seek to maintain or extend it.
31+
Code that cannot be followed by others is likely to be replaced
32+
when it is found (or suspected) to be the source of a bug or limitation,
33+
and then the value of your excellent work is lost.
34+
35+
1. Javadoc on any publicly exposed method or field.
36+
2. 4 spaces for indentation, no tabs.
37+
3. No nested ternary statements (no ternary statements inside other ternaries).
38+
4. A luxurious 100 characters per line.
39+
5. No copy and pasted, repeated code:
40+
if you're doing the same thing twice, make a method.
41+
6. Braces on all loops and `if-else` statements
42+
7. A space between an if and its parenthesis i.e. `if (` instead of `if(`.
43+
8. Spaces between annotation element-value pairs,
44+
i.e. `@ExposedType(name = "unicode", base = PyBaseString.class)`
45+
instead of `@ExposedType(name="unicode",base=PyBaseString.class)`.
46+
9. Methods longer than 10 lines should have whitespace and comments breaking them up into coherent operations.
47+
10. Descriptive names for fields and methods.
48+
11. No @author tags in code.
49+
12. Any field on an object that isn't modified after construction should be final.
50+
13. Fields at the top of the class.
51+
14. Don't declare fields with their default values ie `private Object blah;`
52+
instead of private `Object blah = null;`
53+
and `int i;` instead of `int i = 0;`
54+
15. Comments begin with a space unless they're commented out code:
55+
Poor:
56+
```
57+
//TODO: Not implemented yet
58+
// bar.bar()
59+
```
60+
Better:
61+
```
62+
// TODO: Not implemented yet
63+
//bar.bar()
64+
```
65+
66+
Beyond these rules, follow the Sun Java standards.
67+
68+
> [!NOTE]
69+
> We should provide a set of formatting definitions that can be imported into
70+
> the Eclipse IDE to get it to follow the standards.
71+
> The Java formatter in VSCode will read the rules Eclipse exports.
72+
> In 2025 this was incomplete and provided no way to edit the rules,
73+
> buthings may have moved on,
74+
> see https://code.visualstudio.com/docs/java/java-linting.
75+
76+
77+
### Example (adapted from Sun document)
78+
79+
```java
80+
package org.jython.blah;
81+
import org.jython.blah.BlahBlah;
82+
/**
83+
* Class description goes here.
84+
*/
85+
public class Blah extends SomeClass {
86+
/* A class implementation comment can go here. */
87+
/** classVar1 documentation comment */
88+
public static int classVar1;
89+
/**
90+
* classVar2 documentation comment that happens to be
91+
* more than one line long
92+
*/
93+
private static Object classVar2;
94+
/** instanceVar1 documentation comment */
95+
public Object instanceVar1;
96+
/** instanceVar2 documentation comment */
97+
protected int instanceVar2;
98+
/** instanceVar3 documentation comment */
99+
private Object[] instanceVar3;
100+
101+
/**
102+
* ...constructor Blah documentation comment...
103+
*/
104+
public Blah() {
105+
// ...implementation goes here...
106+
}
107+
108+
/**
109+
* ...method doSomething documentation comment...
110+
*/
111+
public void doSomething() {
112+
// ...implementation goes here...
113+
}
114+
115+
/**
116+
* ...method doSomethingElse documentation comment...
117+
* @param someParam description
118+
*/
119+
public void doSomethingElse(Object someParam) {
120+
// ...implementation goes here...
121+
}
122+
}
123+
```
124+

‎ProcessDocs/contributor_agreement.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Contributor Agreement
2+
3+
Jython is a Python Software Foundation project,
4+
and therefore we use the same process to ensure that
5+
code submitted by you is actually free for us to use,
6+
which is this
7+
[Contributor Agreement](https://www.python.org/psf/contrib/contrib-form/).
8+
9+
Up sides:
10+
* If you are a contributor to CPython, or its documentation, PEPs etc.,
11+
there's nothing else to do.
12+
* When you have signed up, you're all set to contribute to CPython too.
13+
14+
Down side:
15+
* The nice automation of the process built for CPython does not work here
16+
(because Jython is not part of the Python GitHub organisation[^1]).
17+
So only the manual process works.
18+
19+
When you've signed up,
20+
add yourself to the ACKNOWLEDGMENTS file in the form
21+
```
22+
Real Name (GitHub: githubname) C, YYYY-MM-DD
23+
```
24+
where the date is the current date (date of your sign up).
25+
26+
[^1]: Jython moved to GitHub as its own organisation
27+
before CPython made the leap.
28+

0 commit comments

Comments
 (0)