Skip to main content

Development Standards

These standards define the general expectations for contributing code across the Ubujima developer ecosystem.

Individual repositories may add project-specific conventions. Repository-specific guidance takes priority when it is more detailed.

1. Build for Maintainability​

Code should be understandable by people other than its original author.

Prefer:

  • Clear naming
  • Small, focused units of responsibility
  • Explicit behavior
  • Reusable components where appropriate
  • Minimal unnecessary complexity
  • Documentation for non-obvious decisions

2. Respect Architectural Boundaries​

New functionality should fit the responsibility of the domain or component that owns it.

Avoid creating hidden dependencies between unrelated areas of the system.

When introducing a new service or module, explain why a new boundary is justified.

3. Work Through Branches​

Feature work should normally happen on a dedicated branch or fork rather than directly on the stable branch.

Examples:

feature/profile-connections
fix/feed-pagination
docs/api-guidelines
refactor/notification-boundary

Use repository-specific naming conventions where they exist.

4. Commit Clearly​

Commit messages should communicate intent.

Good examples:

Add profile validation
Fix mobile navigation regression
Document notification API
Refactor discovery filters

Avoid vague messages such as:

changes
update
stuff
fix

5. Keep Pull Requests Focused​

A pull request should solve a coherent problem.

Where practical, avoid combining unrelated refactors, features and formatting changes into one large review.

A useful pull request explains:

  • What changed
  • Why it changed
  • How it was tested
  • Known limitations
  • Related issues or decisions

6. Review Before Merge​

Review should consider:

  • Correctness
  • Architecture
  • Security
  • Performance
  • Maintainability
  • Tests
  • Documentation
  • User impact
  • Compatibility

Review is a collaboration process, not only a gate.

7. Test According to Risk​

Testing should match the importance and complexity of the change.

Depending on the project, this may include:

  • Unit tests
  • Integration tests
  • API tests
  • UI tests
  • Manual testing
  • Regression testing
  • Security testing

A change should not knowingly break existing supported behavior.

8. Validate External Input​

Applications and services should treat external input as untrusted.

Validate required fields, formats, permissions and business rules at the appropriate boundary.

9. Protect Secrets​

Never commit:

  • Passwords
  • API keys
  • Tokens
  • Private keys
  • Production credentials
  • Confidential user data

Use approved configuration and secret-management mechanisms.

10. Design APIs as Contracts​

API changes can affect multiple clients and services.

Before changing an established interface, consider backward compatibility and migration requirements.

Avoid exposing internal implementation details unnecessarily through public interfaces.

11. Prefer Clear Domain Ownership​

As the platform becomes more modular, each domain should own its responsibilities and rules.

Avoid designs where every service can directly modify every other domain's data.

Use defined interfaces and events where they provide clearer ownership.

12. Introduce Microservices Intentionally​

A new microservice should solve a real architectural problem.

Good reasons may include:

  • Independent scaling requirements
  • Clear domain ownership
  • Independent deployment needs
  • Reliability isolation
  • Specialized technology requirements
  • Separate security boundaries

Poor reasons include simply wanting more services or copying another company's architecture.

13. Keep Services Operable​

A service is not complete merely because its code works locally.

Where relevant, it should also consider:

  • Configuration
  • Health checks
  • Logging
  • Metrics
  • Failure behavior
  • Deployment
  • Rollback
  • Documentation

14. Document Important Decisions​

Significant architectural decisions should be recorded so future contributors understand the reasoning.

Useful topics include:

  • Why a new service boundary was introduced
  • Why an API contract changed
  • Why a dependency was selected
  • Why a migration is required
  • What alternatives were considered

15. Keep Dependencies Intentional​

Before adding a package or service dependency, consider:

  • Necessity
  • Maintenance quality
  • Security history
  • License compatibility
  • Long-term operational cost
  • Whether an existing dependency already solves the problem

16. Performance​

Avoid obvious performance problems such as:

  • Unbounded queries
  • Unnecessary repeated requests
  • Large payloads without pagination
  • Expensive work inside frequently executed paths
  • Avoidable synchronous blocking

Optimize based on evidence where possible.

17. Accessibility​

User-facing interfaces should consider accessibility from the beginning.

This includes keyboard access, semantic structure, readable contrast, clear labels and assistive-technology compatibility where applicable.

18. Documentation Is Part of the Change​

When behavior, setup, APIs or architecture changes, update the relevant documentation in the same contribution where practical.

19. Production Discipline​

Production releases should be intentional and limited to authorized contributors.

Experiment in appropriate development or staging environments rather than making unreviewed production changes.

20. Public and Private Information​

Public repositories and documentation should not expose information merely because it is technically convenient to document it there.

Keep the following in controlled documentation when appropriate:

  • Internal topology
  • Environment-specific endpoints
  • Production configuration
  • Credentials and access details
  • Security-sensitive implementation information
  • Confidential product or migration plans

Public documentation should focus on interfaces, contribution expectations and engineering principles.

21. Project-Specific Standards​

Different projects may use different languages, frameworks and tooling.

Contributors should follow the formatter, linter, test runner and repository conventions configured for the project they are working on.

22. Ask Before Large Changes​

Before beginning a major rewrite, architecture change or large multi-service implementation, coordinate with project maintainers.

This helps prevent duplicated effort and ensures that the proposed direction aligns with the project's goals.

Good engineering is not only about making something work. It is about making it understandable, secure and sustainable.

Git Collaboration Workflow​

To keep the Developer Hub stable and make collaboration safer, contributors should avoid working directly on the main branch.

The main branch should represent the latest stable and deployable version of the project.

Before Starting Work​

Always begin by updating your local main branch:

git checkout main
git pull origin main

Then create a new branch for your work:

git checkout -b feature/your-feature-name

Use a clear branch name that reflects the purpose of the work.

Examples:

feature/react-challenge
feature/developer-onboarding
docs/api-guidelines
fix/navigation
fix/footer

### Making Changes

Work only on your feature or documentation branch.

Before committing, review what changed:

git status

Stage only the files that are part of your intended change where practical:

git add path/to/file

Then commit with a clear message:

git commit -m "Describe the change clearly"

### Push the Branch

Push the branch to GitHub:

git push -u origin feature/your-feature-name

After the upstream branch has been created, future updates can usually be pushed with:

git push

### Pull Requests

Changes should be merged into main through a Pull Request.

Before merging, reviewers should check:

What files changed
Whether unrelated files were modified
Whether navigation or configuration was unintentionally changed
Whether documentation remains accurate
Whether the project builds successfully
Whether the change introduces security, privacy, or licensing concerns

Where practical, at least one other contributor should review the Pull Request before it is merged.


### Keep Your Branch Updated

If main changes while you are still working, update your branch before final review.

A common approach is:

git checkout main
git pull origin main
git checkout feature/your-feature-name
git merge main

Resolve any conflicts locally, rebuild the project, and test before pushing the updated branch.


### After a Pull Request Is Merged

Return to main and update your local copy:

git checkout main
git pull origin main

The completed local branch can then be removed:

git branch -d feature/your-feature-name


### Important Rules

Contributors should not:

Force-push to main
Develop directly on main
Merge unreviewed changes that affect shared configuration
Commit secrets, credentials, tokens, or production configuration
Include unrelated changes in the same Pull Request

Small, focused Pull Requests are easier to review, test, and maintain.