Jianghu Digital Platform
Login

Open Source Collaboration

12003

If you have any questions, feel free to submit an issue or directly modify and submit a PR!

Submitting an Issue

  • Please specify the type of the issue.
  • Avoid submitting duplicate issues; search existing issues before submitting.
  • Clearly express intent in the labels (refer to Label Classification), title, or content.

Subsequently, the Egg maintainers will confirm the intent of the issue, update appropriate labels, associate milestones, and assign developers.

Labels can be categorized into two types: type and scope.

  • type: the type of the issue, such as feature, bug, documentation, performance, support, etc.
  • scope: the scope of the modified files, such as core: xx, plugin: xx, deps: xx, etc.

Common Label Descriptions

  • support: The issue raised requires collaboration from developers for troubleshooting, consulting, debugging, and other routine technical support.
  • bug: If a potential bug is discovered, please label it as bug and wait for confirmation. Once confirmed as a bug, this issue will be labeled as confirmed.
    • At this point, the issue will be treated with very high priority.
    • If this bug is affecting the normal operation of an online application, it will be labeled as critical, indicating the highest priority and requiring immediate attention!
    • Bugs will be fixed in the minimum required version, for example, if a fix is needed in version 0.9.x, and the current latest version is 1.1.x, then this issue will also be labeled with 0.9, 0.10, 1.0, 1.1, indicating the need for fixes in those versions.
  • core: xx: Indicates that the issue is related to the core kernel, such as core: antx which relates to antx configuration.
  • plugin: xx: Indicates that the issue is related to plugins, such as deps: session which relates to the session plugin.
  • deps: xx: Indicates that the issue is related to dependencies modules, such as deps: egg-cors which relates to the egg-cors module.
  • chore: documentation: Indicates that a documentation-related issue has been discovered and needs documentation clarification.
  • cbd: Indicates that it is related to server deployment.

Writing Documentation

All feature points must be accompanied by supporting documentation. The documentation must meet the following requirements:

  • Clearly explain several aspects of the issue: what (what is it), why (why), how (how to do it), with emphasis based on the nature of the issue.
  • The how section must include detailed and complete operational steps, and if necessary, provide sufficiently simple, runnable example code. All example code should be placed in the eggjs/examples repository.
  • Provide necessary links, such as application processes, terminology explanations, and reference documents.
  • Synchronize modifications in both Chinese and English documentation, or specify in the PR.

Submitting Code

Submitting a Pull Request

If you have developer permissions for the repository and wish to contribute code, you can create a branch to modify the code and submit a PR. The Egg development team will review the code for merging into the main branch. 

# First, create a development branch; the branch name should be meaningful, avoiding names like update, tmp, etc.  
$ git checkout -b branch-name  

# After development is complete, run tests to ensure they pass; if necessary, add or modify test cases.  
$ npm test

After tests pass, submit the code; see the message format below

$ git add .  
$ git commit -m "fix(role): role.use must be xxx"  
$ git push origin branch-name

Since no one can guarantee how much will be remembered after a long time, for the convenience of tracing history later, please ensure to provide the following information when submitting the MR.

  1. Requirement points (generally related to issues or comments count)
  2. Upgrade reasons (different from issues, briefly describe why it needs to be addressed)
  3. Framework test points (can be related to test files, no need for detailed descriptions, just key points)
  4. Focus points (for users, can be omitted, generally for incompatible updates that need extra prompts)

Code Style

Your code style must pass eslint; you can run $ npm run lint for local testing.

Commit Submission Specifications

Submit commits according to the Angular specifications,
so that the history looks clearer and can automatically generate changelogs. 

<type>(<scope>): <subject>  
<BLANK LINE>  
<body>  
<BLANK LINE>  
<footer>

(1) type

The type of the commit, including the following:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code formatting changes that do not affect logic
  • refactor: Code refactoring that theoretically does not affect existing functionality
  • perf: Performance improvements
  • test: Adding or modifying test cases
  • chore: Tool-related changes (including but not limited to documentation, code generation, etc.)
  • deps: Dependency upgrades

(2) scope

The scope of modified files (including but not limited to doc, middleware, core, config, plugin)

(3) subject

Clearly describe what this commit does in one sentence.

(4) body

Supplement the subject, appropriately adding reasons, purposes, and other related factors; this can be omitted.

(5) footer

  • When there are non-compatible changes (Breaking Change), it must be clearly described here
  • Link related issues, such as Closes #1, Closes #2, #3
  • If there are new or modified features, also link the documentation doc and egg-core PRs, such as eggjs/egg-core#123

Example 

fix($compile): couple of unit tests for IE9  

Older IEs serialize HTML uppercased, but IE9 does not...  
Would be better to expect case insensitive, unfortunately Jasmine does  
not allow to use regexps for throw expectations.  

Document change on eggjs/egg#123  

Closes #392  

BREAKING CHANGE:  

  Breaks foo.bar API, use foo.baz instead.

For more details, please refer to the specific documentation.

English Translation Specifications

The English text should be written according to general English grammar rules, but titles are somewhat special and should be written according to the following specifications:

  • Nouns, verbs, pronouns, adjectives, adverbs, etc., should have their first letters capitalized, while prepositions, articles, conjunctions, interjections, and particles should have their first letters in lowercase; the first and last words of the title should have their first letters capitalized regardless of their part of speech.
  • Proper nouns (such as directly quoting a variable or a plugin name, etc.) must be enclosed in backticks (located just below the Esc key) and retain their original casing.
  • Prepositions longer than 5 letters should have their first letters capitalized; otherwise, they should all be in lowercase.
  • If it is an important prompt title or a proper name title (e.g., HTTP request methods: GET, POST, PUT, DELETE), all letters can be capitalized (consider carefully).
  • If the title is a "verb-object" type phrase (e.g., "Configuration Management"), try to translate it into the "object + verb noun" form (Configuration Management) or the "gerund + object" form (Managing Configuration).
  • If the title is treated as a complete English sentence, please follow the grammatical format of English sentences for capitalization (e.g., each title in FAQs is a complete English sentence).

For details, you can refer to English Title Capitalization.

Release Management

Egg releases are based on semver (Semantic Versioning).

Branch Strategy

The master branch is the currently stable release version, and the next branch is for the next major version in development.

  • Only two versions are maintained. Fixes will only be merged into the master and next branches unless there are security issues. We encourage upper-level frameworks to upgrade to the latest stable major version.
  • All API deprecations must be indicated with a deprecate notice on the current stable version and ensure compatibility with the new version release.
  • The master branch does not set a publish tag. Upper-level frameworks depend on stable versions based on semver.
  • The next branch sets the tag to next. Upper-level frameworks can reference the development version for testing via egg@next.
  • The versions maintained by Egg are based on Milestones. As long as a version is open, it will be fixed.

Release Strategy

Each major version has a release manager (PM) responsible for management. His/her responsibilities include:

Preparation:

  • Establish Milestones, confirm requirements associated with the Milestone, and assign and update Issues. For example, 1.x Milestone.
  • Create a new next branch from the master branch and set the tag to next.

Before Release:

  • Confirm that all Issues in the current Milestone are closed or can be postponed. Complete performance testing.
  • Initiate a new Release Proposal MR, writing the History according to Node CHANGELOG. Correct any version-related content in the documentation; commits can be automatically generated with the following command: 
    $ npm run commits
  • Designate the PM for the next major version.

During Release:

  • Back up the old stable version (master) to a branch named after the current major version (e.g., 1.x), and set the tag to release-{v}.x (where v is the current version, e.g., release-1.x).
  • Push the next branch to master, becoming the new stable version branch. Remove the next tag and modify the README content related to the branch.
  • Release the new stable version to npm and notify upper-level frameworks to update.
  • Before executing npm publish, please read How I Publish an npm Package.

All tag settings mentioned above refer to setting the npm tag in package.json. 

"publishConfig": {  
  "tag": "next"  
}